Greengrass v2 Developer Guide
Uploaded by
Nipun KumarGreengrass v2 Developer Guide
Uploaded by
Nipun KumarAWS IoT Greengrass
Developer Guide, Version 2
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass: Developer Guide, Version 2
Copyright © Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not
Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or
discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may
or may not be affiliated with, connected to, or sponsored by Amazon.
AWS IoT Greengrass Developer Guide, Version 2
Table of Contents
What is AWS IoT Greengrass? .............................................................................................................. 1
For first-time users ..................................................................................................................... 1
For existing users ....................................................................................................................... 1
How AWS IoT Greengrass works ................................................................................................... 2
Key concepts ..................................................................................................................... 2
Features of AWS IoT Greengrass .......................................................................................... 4
Greengrass feature compatibility by operating system .................................................................... 5
Move from Version 1 .................................................................................................................. 8
Differences between V1 and V2 ........................................................................................... 8
Run V1 applications on V2 ................................................................................................ 10
What's new in Version 2 ............................................................................................................ 12
AWS IoT Greengrass Core v2.5.2 software update ................................................................. 13
AWS IoT Greengrass Core v2.5.1 software update ................................................................. 14
AWS IoT Greengrass Core v2.5.0 software update ................................................................. 15
AWS IoT Greengrass Core v2.4.0 software update ................................................................. 18
AWS IoT Greengrass Core v2.3.0 software update ................................................................. 20
AWS IoT Greengrass Core v2.2.0 software update ................................................................. 21
AWS IoT Greengrass Core v2.1.0 software update ................................................................. 23
AWS IoT Greengrass Core v2.0.5 software update ................................................................. 28
AWS IoT Greengrass Core v2.0.4 software update ................................................................. 29
Getting started tutorial ..................................................................................................................... 31
Prerequisites ............................................................................................................................ 31
Step 1: Set up an AWS account .................................................................................................. 32
Step 2: Set up your environment ............................................................................................... 33
Step 3: Install the AWS IoT Greengrass Core software ................................................................... 35
(Optional) Run the Greengrass software (Linux) .................................................................... 40
Verify the Greengrass CLI installation on the device .............................................................. 41
Step 4: Develop and test a component on your device .................................................................. 42
Step 5: Create your component in the AWS IoT Greengrass service ................................................. 50
Step 6: Deploy your component ................................................................................................. 58
Next steps ............................................................................................................................... 60
Setting up Greengrass core devices .................................................................................................... 62
Supported platforms and requirements ....................................................................................... 62
Supported platforms ........................................................................................................ 62
Device requirements ......................................................................................................... 63
Lambda function requirements .......................................................................................... 64
Feature considerations for Windows devices ................................................................................ 65
Set up an AWS account ............................................................................................................. 66
Install the AWS IoT Greengrass Core software .............................................................................. 67
Install with automatic provisioning ..................................................................................... 69
Install with manual provisioning ......................................................................................... 76
Install with fleet provisioning ............................................................................................. 92
Install with custom provisioning ....................................................................................... 117
Installer arguments ......................................................................................................... 126
Run the AWS IoT Greengrass Core software ............................................................................... 128
Check if the AWS IoT Greengrass Core software runs as a system service ................................ 129
Run the AWS IoT Greengrass Core software as a system service ............................................ 130
Run the AWS IoT Greengrass Core software without a system service .................................... 130
Run AWS IoT Greengrass in Docker ........................................................................................... 131
Supported platforms and requirements ............................................................................. 131
Software downloads ....................................................................................................... 132
Choose how to provision AWS resources ............................................................................ 133
Build the AWS IoT Greengrass image from a Dockerfile ....................................................... 133
Run AWS IoT Greengrass in Docker with automatic provisioning ........................................... 137
iii
AWS IoT Greengrass Developer Guide, Version 2
Run AWS IoT Greengrass in Docker with manual provisioning ............................................... 142
Troubleshooting AWS IoT Greengrass in a Docker container ................................................. 155
Configure the AWS IoT Greengrass Core software ....................................................................... 157
Deploy the Greengrass nucleus component ........................................................................ 158
Configure the Greengrass nucleus as a system service ......................................................... 158
Control memory allocation with JVM options ..................................................................... 160
Configure the user that runs components .......................................................................... 161
Configure system resource limits ...................................................................................... 164
Connect on port 443 or through a network proxy ............................................................... 165
Configure MQTT timeouts and cache settings .................................................................... 170
Update the AWS IoT Greengrass Core software (OTA) .................................................................. 170
Requirements ................................................................................................................. 170
Considerations for core devices ........................................................................................ 170
Greengrass nucleus update behavior ................................................................................. 171
Perform an OTA update .................................................................................................. 172
Uninstall the AWS IoT Greengrass Core software ........................................................................ 172
AWS-provided components .............................................................................................................. 175
Greengrass nucleus ................................................................................................................. 181
Versions ........................................................................................................................ 181
Operating system ........................................................................................................... 182
Requirements ................................................................................................................. 182
Dependencies ................................................................................................................. 182
Installation .................................................................................................................... 182
Configuration ................................................................................................................. 182
Local log file .................................................................................................................. 189
Changelog ..................................................................................................................... 190
Client device auth ................................................................................................................... 194
Versions ........................................................................................................................ 195
Type ............................................................................................................................. 195
Operating system ........................................................................................................... 195
Requirements ................................................................................................................. 195
Dependencies ................................................................................................................. 196
Configuration ................................................................................................................. 197
Local log file .................................................................................................................. 200
Changelog ..................................................................................................................... 201
CloudWatch metrics ................................................................................................................ 201
Versions ........................................................................................................................ 202
Type ............................................................................................................................. 202
Operating system ........................................................................................................... 202
Requirements ................................................................................................................. 203
Dependencies ................................................................................................................. 205
Configuration ................................................................................................................. 207
Input data ..................................................................................................................... 211
Output data ................................................................................................................... 213
Licenses ......................................................................................................................... 214
Local log file .................................................................................................................. 214
Changelog ..................................................................................................................... 215
See also ........................................................................................................................ 215
Docker application manager ..................................................................................................... 216
Versions ........................................................................................................................ 216
Type ............................................................................................................................. 216
Operating system ........................................................................................................... 216
Requirements ................................................................................................................. 216
Dependencies ................................................................................................................. 218
Configuration ................................................................................................................. 219
Local log file .................................................................................................................. 219
Changelog ..................................................................................................................... 220
iv
AWS IoT Greengrass Developer Guide, Version 2
See also ........................................................................................................................ 220
Edge connector for Kinesis Video Streams ................................................................................. 220
Versions ........................................................................................................................ 221
Type ............................................................................................................................. 221
Operating system ........................................................................................................... 221
Requirements ................................................................................................................. 221
Dependencies ................................................................................................................. 223
Configuration ................................................................................................................. 224
Licenses ......................................................................................................................... 224
Usage ............................................................................................................................ 224
Local log file .................................................................................................................. 224
Changelog ..................................................................................................................... 224
See also ........................................................................................................................ 225
Greengrass CLI ....................................................................................................................... 225
Versions ........................................................................................................................ 226
Type ............................................................................................................................. 226
Operating system ........................................................................................................... 226
Requirements ................................................................................................................. 226
Dependencies ................................................................................................................. 227
Configuration ................................................................................................................. 228
Local log file .................................................................................................................. 229
Changelog ..................................................................................................................... 229
AWS IoT Device Defender ........................................................................................................ 230
Versions ........................................................................................................................ 231
Type ............................................................................................................................. 231
Operating system ........................................................................................................... 231
Requirements ................................................................................................................. 231
Dependencies ................................................................................................................. 233
Configuration ................................................................................................................. 235
Input data ..................................................................................................................... 237
Output data ................................................................................................................... 237
Local log file .................................................................................................................. 238
Licenses ......................................................................................................................... 239
Changelog ..................................................................................................................... 239
IP detector ............................................................................................................................ 240
Versions ........................................................................................................................ 240
Type ............................................................................................................................. 240
Operating system ........................................................................................................... 241
Requirements ................................................................................................................. 241
Dependencies ................................................................................................................. 241
Configuration ................................................................................................................. 242
Local log file .................................................................................................................. 243
Changelog ..................................................................................................................... 243
Kinesis Data Firehose .............................................................................................................. 244
Versions ........................................................................................................................ 244
Type ............................................................................................................................. 244
Operating system ........................................................................................................... 244
Requirements ................................................................................................................. 244
Dependencies ................................................................................................................. 246
Configuration ................................................................................................................. 248
Input data ..................................................................................................................... 250
Output data ................................................................................................................... 251
Local log file .................................................................................................................. 251
Licenses ......................................................................................................................... 252
Changelog ..................................................................................................................... 252
See also ........................................................................................................................ 252
Lambda launcher .................................................................................................................... 252
v
AWS IoT Greengrass Developer Guide, Version 2
Versions ........................................................................................................................ 253
Type ............................................................................................................................. 253
Operating system ........................................................................................................... 253
Requirements ................................................................................................................. 253
Dependencies ................................................................................................................. 253
Configuration ................................................................................................................. 254
Local log file .................................................................................................................. 254
Changelog ..................................................................................................................... 254
Lambda manager ................................................................................................................... 255
Versions ........................................................................................................................ 255
Operating system ........................................................................................................... 255
Type ............................................................................................................................. 255
Requirements ................................................................................................................. 256
Dependencies ................................................................................................................. 256
Configuration ................................................................................................................. 257
Local log file .................................................................................................................. 257
Changelog ..................................................................................................................... 258
Lambda runtimes ................................................................................................................... 258
Versions ........................................................................................................................ 259
Type ............................................................................................................................. 259
Operating system ........................................................................................................... 259
Requirements ................................................................................................................. 259
Dependencies ................................................................................................................. 259
Configuration ................................................................................................................. 259
Local log file .................................................................................................................. 259
Changelog ..................................................................................................................... 259
Legacy subscription router ....................................................................................................... 260
Versions ........................................................................................................................ 260
Type ............................................................................................................................. 260
Operating system ........................................................................................................... 261
Dependencies ................................................................................................................. 261
Configuration ................................................................................................................. 262
Local log file .................................................................................................................. 265
Changelog ..................................................................................................................... 265
Local debug console ............................................................................................................... 265
Versions ........................................................................................................................ 266
Type ............................................................................................................................. 266
Operating system ........................................................................................................... 266
Requirements ................................................................................................................. 266
Dependencies ................................................................................................................. 266
Configuration ................................................................................................................. 268
Usage ............................................................................................................................ 269
Local log file .................................................................................................................. 272
Changelog ..................................................................................................................... 273
Log manager ......................................................................................................................... 273
Versions ........................................................................................................................ 274
Type ............................................................................................................................. 274
Operating system ........................................................................................................... 275
Requirements ................................................................................................................. 275
Dependencies ................................................................................................................. 276
Configuration ................................................................................................................. 277
Usage ............................................................................................................................ 285
Local log file .................................................................................................................. 287
Changelog ..................................................................................................................... 287
Machine learning components .................................................................................................. 288
SageMaker Edge Manager ................................................................................................ 292
DLR image classification .................................................................................................. 299
vi
AWS IoT Greengrass Developer Guide, Version 2
DLR object detection ...................................................................................................... 306
DLR image classification model store ................................................................................ 313
DLR object detection model store ..................................................................................... 316
DLR installer .................................................................................................................. 319
TensorFlow Lite image classification .................................................................................. 324
TensorFlow Lite object detection ...................................................................................... 329
TensorFlow Lite image classification model store ................................................................ 334
TensorFlow Lite object detection model store .................................................................... 337
TensorFlow Lite installer .................................................................................................. 339
Modbus-RTU protocol adapter ................................................................................................. 344
Versions ........................................................................................................................ 345
Type ............................................................................................................................. 345
Operating system ........................................................................................................... 345
Requirements ................................................................................................................. 345
Dependencies ................................................................................................................. 346
Configuration ................................................................................................................. 348
Input data ..................................................................................................................... 350
Output data ................................................................................................................... 351
Modbus RTU requests and responses ................................................................................ 353
Local log file .................................................................................................................. 359
Licenses ......................................................................................................................... 359
Changelog ..................................................................................................................... 359
MQTT bridge .......................................................................................................................... 360
Versions ........................................................................................................................ 360
Type ............................................................................................................................. 361
Operating system ........................................................................................................... 361
Requirements ................................................................................................................. 361
Dependencies ................................................................................................................. 361
Configuration ................................................................................................................. 361
Local log file .................................................................................................................. 364
Changelog ..................................................................................................................... 364
MQTT broker (Moquette) ......................................................................................................... 365
Versions ........................................................................................................................ 365
Type ............................................................................................................................. 365
Operating system ........................................................................................................... 366
Requirements ................................................................................................................. 366
Dependencies ................................................................................................................. 366
Configuration ................................................................................................................. 366
Local log file .................................................................................................................. 367
Changelog ..................................................................................................................... 368
Nucleus telemetry emitter ....................................................................................................... 368
Versions ........................................................................................................................ 368
Type ............................................................................................................................. 368
Operating system ........................................................................................................... 369
Dependencies ................................................................................................................. 369
Configuration ................................................................................................................. 369
Output data ................................................................................................................... 370
Usage ............................................................................................................................ 373
Local log file .................................................................................................................. 373
Changelog ..................................................................................................................... 374
Secret manager ...................................................................................................................... 374
Versions ........................................................................................................................ 375
Type ............................................................................................................................. 375
Operating system ........................................................................................................... 375
Requirements ................................................................................................................. 375
Dependencies ................................................................................................................. 376
Configuration ................................................................................................................. 377
vii
AWS IoT Greengrass Developer Guide, Version 2
Local log file .................................................................................................................. 378
Changelog ..................................................................................................................... 378
Secure tunneling .................................................................................................................... 379
Versions ........................................................................................................................ 379
Type ............................................................................................................................. 379
Operating system ........................................................................................................... 380
Requirements ................................................................................................................. 380
Dependencies ................................................................................................................. 380
Configuration ................................................................................................................. 381
Local log file .................................................................................................................. 382
Licenses ......................................................................................................................... 383
See also ........................................................................................................................ 383
Changelog ..................................................................................................................... 383
Shadow manager .................................................................................................................... 383
Versions ........................................................................................................................ 384
Type ............................................................................................................................. 384
Operating system ........................................................................................................... 384
Requirements ................................................................................................................. 384
Dependencies ................................................................................................................. 385
Configuration ................................................................................................................. 385
Local log file .................................................................................................................. 388
Changelog ..................................................................................................................... 388
Amazon SNS .......................................................................................................................... 389
Versions ........................................................................................................................ 389
Type ............................................................................................................................. 389
Operating system ........................................................................................................... 390
Requirements ................................................................................................................. 390
Dependencies ................................................................................................................. 391
Configuration ................................................................................................................. 393
Input data ..................................................................................................................... 395
Output data ................................................................................................................... 396
Local log file .................................................................................................................. 397
Licenses ......................................................................................................................... 397
Changelog ..................................................................................................................... 397
Stream manager ..................................................................................................................... 398
Versions ........................................................................................................................ 398
Type ............................................................................................................................. 398
Operating system ........................................................................................................... 398
Requirements ................................................................................................................. 398
Dependencies ................................................................................................................. 399
Configuration ................................................................................................................. 401
Local log file .................................................................................................................. 402
Changelog ..................................................................................................................... 403
Systems Manager Agent .......................................................................................................... 403
Versions ........................................................................................................................ 404
Type ............................................................................................................................. 404
Operating system ........................................................................................................... 404
Requirements ................................................................................................................. 404
Dependencies ................................................................................................................. 405
Configuration ................................................................................................................. 406
Local log file .................................................................................................................. 407
See also ........................................................................................................................ 407
Changelog ..................................................................................................................... 407
Token exchange service ........................................................................................................... 407
Versions ........................................................................................................................ 408
Type ............................................................................................................................. 408
Operating system ........................................................................................................... 408
viii
AWS IoT Greengrass Developer Guide, Version 2
Dependencies ................................................................................................................. 408
Configuration ................................................................................................................. 408
Local log file .................................................................................................................. 408
Changelog ..................................................................................................................... 409
IoT SiteWise OPC-UA collector ................................................................................................. 409
Versions ........................................................................................................................ 410
Type ............................................................................................................................. 410
Operating system ........................................................................................................... 410
Requirements ................................................................................................................. 410
Dependencies ................................................................................................................. 410
Configuration ................................................................................................................. 411
Output data ................................................................................................................... 411
Local log file .................................................................................................................. 411
Licenses ......................................................................................................................... 411
Changelog ..................................................................................................................... 411
See also ........................................................................................................................ 411
IoT SiteWise publisher ............................................................................................................. 411
Versions ........................................................................................................................ 412
Type ............................................................................................................................. 412
Operating system ........................................................................................................... 412
Requirements ................................................................................................................. 412
Dependencies ................................................................................................................. 413
Configuration ................................................................................................................. 413
Input data ..................................................................................................................... 413
Local log file .................................................................................................................. 414
Licenses ......................................................................................................................... 414
Changelog ..................................................................................................................... 414
See also ........................................................................................................................ 414
IoT SiteWise processor ............................................................................................................ 414
Versions ........................................................................................................................ 415
Type ............................................................................................................................. 415
Operating system ........................................................................................................... 415
Requirements ................................................................................................................. 415
Dependencies ................................................................................................................. 416
Configuration ................................................................................................................. 417
Local log file .................................................................................................................. 417
Licenses ......................................................................................................................... 417
Changelog ..................................................................................................................... 418
See also ........................................................................................................................ 418
Community components .................................................................................................................. 419
Greengrass development tools ......................................................................................................... 420
Greengrass Development Kit CLI ............................................................................................... 420
Prerequisites .................................................................................................................. 421
Install the Greengrass Development Kit CLI ........................................................................ 421
GDK CLI commands ........................................................................................................ 422
GDK CLI configuration file ............................................................................................... 425
Greengrass Command Line Interface ......................................................................................... 428
Install the Greengrass CLI ................................................................................................ 428
Greengrass CLI commands ............................................................................................... 431
Develop components ...................................................................................................................... 440
Component lifecycle ............................................................................................................... 441
Component types ................................................................................................................... 441
Create components ................................................................................................................. 442
Create a component (GDK CLI) ......................................................................................... 443
Create a component (shell commands) .............................................................................. 447
Test components with local deployments .................................................................................. 449
Publish components to deploy ................................................................................................. 451
ix
AWS IoT Greengrass Developer Guide, Version 2
Publish a component (GDK CLI) ........................................................................................ 451
Publish a component (shell commands) ............................................................................. 452
Interact with AWS services ....................................................................................................... 454
Run a Docker container ........................................................................................................... 456
Requirements ................................................................................................................. 457
Run a Docker container from a public image in Amazon ECR or Docker Hub ............................ 459
Run a Docker container from a private image in Amazon ECR ............................................... 461
Run a Docker container from an image in Amazon S3 ......................................................... 463
Use interprocess communication in Docker container components ......................................... 465
Use AWS credentials in Docker container components (Linux) ............................................... 467
Use stream manager in Docker container components (Linux) ............................................... 469
Recipe reference ..................................................................................................................... 471
Recipe format ................................................................................................................ 472
Recipe variables .............................................................................................................. 484
Recipe examples ............................................................................................................. 485
Environment variables ............................................................................................................. 489
Deploy components to devices ......................................................................................................... 491
Create deployments ................................................................................................................ 493
Update component configurations .................................................................................... 500
Revise deployments ................................................................................................................ 502
Cancel deployments ................................................................................................................ 504
Check deployment status ........................................................................................................ 504
Check deployment status ................................................................................................ 505
Check device deployment status ....................................................................................... 505
Logging and monitoring .................................................................................................................. 506
Monitoring tools ..................................................................................................................... 506
Monitor Greengrass logs .......................................................................................................... 506
Access file system logs .................................................................................................... 507
Access CloudWatch Logs .................................................................................................. 509
Access system service logs ............................................................................................... 510
Enable logging to CloudWatch Logs .................................................................................. 510
Configure logging for AWS IoT Greengrass ........................................................................ 511
AWS CloudTrail logs ........................................................................................................ 512
Log API calls with CloudTrail .................................................................................................... 513
AWS IoT Greengrass V2 information in CloudTrail ............................................................... 513
Understanding AWS IoT Greengrass V2 log file entries ........................................................ 514
Gather system health telemetry data ........................................................................................ 515
Telemetry metrics ........................................................................................................... 515
Configure telemetry agent settings ................................................................................... 517
Subscribe to telemetry data in EventBridge ....................................................................... 517
Check core device status ......................................................................................................... 521
Check health of a core device .......................................................................................... 521
Check health of a core device group ................................................................................. 522
Check core device component status ................................................................................. 522
Run Lambda functions .................................................................................................................... 523
Requirements ......................................................................................................................... 523
Configure Lambda function lifecycle ......................................................................................... 524
Configure Lambda function containerization .............................................................................. 524
Import a Lambda function as a component (console) .................................................................. 526
Step 1: Choose a Lambda function to import ..................................................................... 526
Step 2: Configure Lambda function parameters .................................................................. 527
Step 3: (Optional) Specify supported platforms for the Lambda function ............................... 528
Step 4: (Optional) Specify component dependencies for the Lambda function ......................... 528
Step 5: (Optional) Run the Lambda function in a container .................................................. 529
Step 6: Create the Lambda function component ................................................................. 530
Import a Lambda function (CLI) ............................................................................................... 530
Step 1: Define the Lambda function configuration .............................................................. 530
x
AWS IoT Greengrass Developer Guide, Version 2
Step 2: Create the Lambda function component ................................................................. 543
Communicate with the Greengrass nucleus, other components, and AWS IoT Core .................................. 545
Supported SDKs ..................................................................................................................... 545
Connect to the AWS IoT Greengrass Core IPC service .................................................................. 546
Authorize components to perform IPC operations ....................................................................... 552
Subscribe to IPC event streams ................................................................................................ 554
Define subscription handlers ............................................................................................ 554
Best practices for subscription handlers ............................................................................. 555
Example subscription handlers ......................................................................................... 556
Publish/subscribe local messages ............................................................................................. 561
Authorization ................................................................................................................. 561
PublishToTopic ............................................................................................................... 562
SubscribeToTopic ............................................................................................................ 565
Examples ....................................................................................................................... 571
Publish/subscribe AWS IoT Core MQTT messages ....................................................................... 586
Authorization ................................................................................................................. 586
PublishToIoTCore ............................................................................................................ 587
SubscribeToIoTCore ......................................................................................................... 590
Examples ....................................................................................................................... 596
Interact with component lifecycle ............................................................................................. 601
Authorization ................................................................................................................. 602
UpdateState ................................................................................................................... 603
SubscribeToComponentUpdates ....................................................................................... 603
DeferComponentUpdate .................................................................................................. 604
PauseComponent ............................................................................................................ 605
ResumeComponent ......................................................................................................... 605
Interact with component configuration ..................................................................................... 606
GetConfiguration ............................................................................................................ 607
UpdateConfiguration ....................................................................................................... 607
SubscribeToConfigurationUpdate ...................................................................................... 608
SubscribeToValidateConfigurationUpdates ......................................................................... 609
SendConfigurationValidityReport ...................................................................................... 610
Retrieve secret values ............................................................................................................. 610
Authorization ................................................................................................................. 611
GetSecretValue ............................................................................................................... 611
Examples ....................................................................................................................... 614
Interact with local shadows ..................................................................................................... 618
Minimum SDK versions .................................................................................................... 619
Authorization ................................................................................................................. 619
GetThingShadow ............................................................................................................ 622
UpdateThingShadow ....................................................................................................... 626
DeleteThingShadow ........................................................................................................ 630
ListNamedShadowsForThing ............................................................................................ 633
Interact with local IoT devices .......................................................................................................... 638
Tutorial: Connect and test client devices .................................................................................... 638
Prerequisites .................................................................................................................. 639
Review and update the core device AWS IoT policy ............................................................. 639
Enable client device support ............................................................................................ 640
Connect client devices ..................................................................................................... 643
Develop a component that interacts with client devices ....................................................... 645
Client device components ........................................................................................................ 650
Connect client devices to core devices ....................................................................................... 643
Greengrass components for client device support ............................................................... 651
Configure cloud discovery (console) .................................................................................. 652
Configure cloud discovery (AWS CLI) ................................................................................. 652
Associate client devices ................................................................................................... 652
Manage core device endpoints ......................................................................................... 654
xi
AWS IoT Greengrass Developer Guide, Version 2
Test communications ...................................................................................................... 657
Greengrass discovery RESTful API ..................................................................................... 664
Relay MQTT messages between client devices and AWS IoT Core .................................................. 668
Configure and deploy the MQTT bridge component ............................................................ 669
Relay MQTT messages ..................................................................................................... 669
Interact with client devices in components ................................................................................ 670
Configure and deploy the MQTT bridge component ............................................................ 671
Receive MQTT messages from client devices ...................................................................... 671
Send MQTT messages to client devices ............................................................................. 672
Troubleshooting ..................................................................................................................... 672
Greengrass discovery issues ............................................................................................. 672
Interact with device shadows ........................................................................................................... 678
Interact with shadows in components ....................................................................................... 678
Retrieve and modify shadow states ................................................................................... 678
React to shadow state changes ........................................................................................ 679
Sync local device shadows with AWS IoT Core ............................................................................ 680
Prerequisites .................................................................................................................. 680
Configure the shadow manager component ....................................................................... 680
Sync local shadows ......................................................................................................... 681
Manage data streams ...................................................................................................................... 682
Stream management workflow ................................................................................................ 682
Requirements ......................................................................................................................... 683
Data security .......................................................................................................................... 683
Local data security .......................................................................................................... 683
Client authentication ....................................................................................................... 684
See also ................................................................................................................................ 684
Create custom components that use stream manager ................................................................. 684
Define component recipes that use stream manager ........................................................... 685
Connect to stream manager in application code ................................................................. 693
Use StreamManagerClient to work with streams ......................................................................... 695
Create message stream ................................................................................................... 695
Append message ............................................................................................................ 698
Read messages ............................................................................................................... 702
List streams ................................................................................................................... 704
Describe message stream ................................................................................................ 705
Update message stream .................................................................................................. 706
Delete message stream ................................................................................................... 709
See also ........................................................................................................................ 710
Export configurations for supported cloud destinations ....................................................... 710
Configure stream manager ...................................................................................................... 720
Stream manager parameters ............................................................................................ 721
See also ........................................................................................................................ 722
Perform machine learning inference ................................................................................................. 723
How AWS IoT Greengrass ML inference works ............................................................................ 723
What's different in Version 2? .................................................................................................. 724
Requirements ......................................................................................................................... 724
Supported model sources ........................................................................................................ 724
Supported runtimes ................................................................................................................ 725
Machine learning components .................................................................................................. 725
Perform sample image classification inference ........................................................................... 729
Prerequisites .................................................................................................................. 729
Step 1: Subscribe to the default notifications topic ............................................................. 730
Step 2: Deploy the TensorFlow Lite image classification component ...................................... 730
Step 3: View inference results .......................................................................................... 731
Next steps ..................................................................................................................... 733
Perform sample image classification inference on images from a camera ....................................... 733
Prerequisites .................................................................................................................. 733
xii
AWS IoT Greengrass Developer Guide, Version 2
Step 1: Configure the camera module on your device .......................................................... 734
Step 2: Verify your subscription to the default notifications topic .......................................... 736
Step 3: Modify the TensorFlow Lite image classification component configuration and deploy it . 736
Step 4: View inference results .......................................................................................... 738
Next steps ..................................................................................................................... 738
Use SageMaker Edge Manager ................................................................................................. 738
How it works ................................................................................................................. 739
Requirements ................................................................................................................. 739
Get started with SageMaker Edge Manager ........................................................................ 740
Customize your machine learning components ........................................................................... 746
Modify the configuration of a public inference component ................................................... 747
Use a custom model with the sample inference component ................................................. 748
Create custom machine learning components .................................................................... 751
Create a custom inference component .............................................................................. 753
Troubleshooting ..................................................................................................................... 757
Failed to fetch library ..................................................................................................... 758
Cannot open shared object file ........................................................................................ 758
<library> not found ........................................................................................................ 758
No CUDA-capable device is detected ................................................................................. 759
No such file or directory .................................................................................................. 759
Memory errors ............................................................................................................... 759
Disk space errors ............................................................................................................ 760
Timeout errors ............................................................................................................... 760
Manage core devices with AWS Systems Manager ............................................................................... 761
Install the Systems Manager Agent ........................................................................................... 761
Step 1: Complete general Systems Manager setup steps ...................................................... 762
Step 2: Create an IAM service role for Systems Manager ...................................................... 762
Step 3: Add permissions to the token exchange role ........................................................... 762
Step 4: Deploy the Systems Manager Agent component ...................................................... 765
Step 5: Verify core device registration with Systems Manager ............................................... 767
Uninstall the Systems Manager Agent ....................................................................................... 768
Step 1: Deregister the core device from Systems Manager .................................................... 768
Step 2: Uninstall the Systems Manager Agent component .................................................... 768
Step 3: Uninstall the Systems Manager Agent software ....................................................... 769
Security ......................................................................................................................................... 770
Data protection ...................................................................................................................... 770
Data encryption ............................................................................................................. 771
Device authentication and authorization .................................................................................... 773
X.509 certificates ............................................................................................................ 773
AWS IoT policies ............................................................................................................. 774
Update a core device's AWS IoT policy .............................................................................. 776
Minimal AWS IoT policy ................................................................................................... 777
Minimal AWS IoT policy to support client devices ............................................................... 779
Minimal AWS IoT policy for client devices .......................................................................... 780
Identity and access management .............................................................................................. 781
Audience ....................................................................................................................... 782
Authenticating with identities .......................................................................................... 782
Managing access using policies ......................................................................................... 784
See also ........................................................................................................................ 785
How AWS IoT Greengrass works with IAM .......................................................................... 785
Identity-based policy examples ........................................................................................ 789
Authorize core devices to interact with AWS services ........................................................... 790
Minimal IAM policy for installer to provision resources ........................................................ 793
Greengrass service role ................................................................................................... 796
AWS managed policies .................................................................................................... 801
Cross-service confused deputy prevention ......................................................................... 805
Troubleshooting identity and access issues ........................................................................ 805
xiii
AWS IoT Greengrass Developer Guide, Version 2
Allow device traffic through a proxy or firewall .......................................................................... 807
Endpoints for basic operation .......................................................................................... 807
Endpoints for installation with automatic provisioning ........................................................ 809
Endpoints for AWS-provided components .......................................................................... 810
Compliance validation ............................................................................................................. 810
Resilience .............................................................................................................................. 811
Infrastructure security ............................................................................................................. 811
Configuration and vulnerability analysis .................................................................................... 812
Code integrity ........................................................................................................................ 812
VPC endpoints (AWS PrivateLink) ............................................................................................. 813
Considerations for AWS IoT Greengrass VPC endpoints ........................................................ 814
Create an interface VPC endpoint for AWS IoT Greengrass control plane operations ................. 814
Creating a VPC endpoint policy for AWS IoT Greengrass ...................................................... 814
Security best practices ............................................................................................................ 815
Grant minimum possible permissions ................................................................................ 815
Don't hardcode credentials in Greengrass components ........................................................ 815
Don't log sensitive information ........................................................................................ 815
Keep your device clock in sync ......................................................................................... 816
See also ........................................................................................................................ 816
Using AWS IoT Device Tester for AWS IoT Greengrass V2 ..................................................................... 817
AWS IoT Greengrass qualification suite ...................................................................................... 817
Custom test suites .................................................................................................................. 818
Supported versions of AWS IoT Device Tester for AWS IoT Greengrass V2 ....................................... 818
Latest IDT version for AWS IoT Greengrass V2 .................................................................... 818
Earlier IDT versions for AWS IoT Greengrass ....................................................................... 819
Unsupported versions of AWS IoT Device Tester for AWS IoT Greengrass V2 ........................... 819
Use IDT to run the AWS IoT Greengrass qualification suite ........................................................... 820
Test suite versions .......................................................................................................... 821
Test group descriptions ................................................................................................... 821
Prerequisites .................................................................................................................. 824
Configure your device to run IDT tests .............................................................................. 832
Configure IDT settings ..................................................................................................... 836
Run the AWS IoT Greengrass qualification suite .................................................................. 843
Understanding results and logs ........................................................................................ 845
Use IDT to develop and run your own test suites ........................................................................ 847
Download the latest version of IDT for AWS IoT Greengrass ................................................. 824
Test suite creation workflow ............................................................................................ 848
Tutorial: Build and run the sample IDT test suite ................................................................ 848
Tutorial: Develop a simple IDT test suite ............................................................................ 852
Create IDT test suite configuration files ............................................................................. 858
Configure the IDT state machine ...................................................................................... 863
Create IDT test case executables ....................................................................................... 879
Use the IDT context ........................................................................................................ 884
Configure settings for test runners ................................................................................... 886
Debug and run custom test suites .................................................................................... 894
Review IDT test results and logs ....................................................................................... 896
IDT usage metrics ........................................................................................................... 900
Troubleshooting IDT for AWS IoT Greengrass V2 ........................................................................ 905
Where to look for errors ................................................................................................. 905
Resolving IDT for AWS IoT Greengrass V2 errors ................................................................. 905
Support policy for AWS IoT Device Tester for AWS IoT Greengrass ................................................ 910
Troubleshooting ............................................................................................................................. 911
View AWS IoT Greengrass Core software and component logs ...................................................... 911
AWS IoT Greengrass Core software issues .................................................................................. 911
Unable to set up core device ........................................................................................... 911
Unable to set up nucleus as a system service ..................................................................... 912
Unable to connect to AWS IoT Core .................................................................................. 912
xiv
AWS IoT Greengrass Developer Guide, Version 2
Out of memory error ...................................................................................................... 912
Unable to install Greengrass CLI ....................................................................................... 912
User root is not allowed to execute .................................................................................. 913
Failed to map segment from shared object: operation not permitted ..................................... 913
AWS IoT Greengrass cloud issues .............................................................................................. 913
An error occurred (AccessDeniedException) when calling the CreateComponentVersion
operation: User: arn:aws:iam::123456789012:user/<username> is not authorized to perform:
null ............................................................................................................................... 913
Core device deployment issues ................................................................................................. 913
Error: com.aws.greengrass.componentmanager.exceptions.PackageDownloadException: Failed
to download artifact ....................................................................................................... 914
Error:
com.aws.greengrass.componentmanager.exceptions.ArtifactChecksumMismatchException:
Integrity check for downloaded artifact failed. Probably due to file corruption. ....................... 914
Error:
com.aws.greengrass.componentmanager.exceptions.NoAvailableComponentVersionException:
Failed to negotiate component <name> version with cloud and no local applicable version
satisfying requirement <requirements> ............................................................................. 915
software.amazon.awssdk.services.secretsmanager.model.SecretsManagerException: User:
<user> is not authorized to perform: secretsmanager:GetSecretValue on resource: <arn> .......... 915
Info:
com.aws.greengrass.deployment.exceptions.RetryableDeploymentDocumentDownloadException:
Greengrass Cloud Service returned an error when getting full deployment configuration .......... 916
Info: com.aws.greengrass.deployment.DeploymentDocumentDownloader: Calling Greengrass
cloud to get full deployment configuration ........................................................................ 916
Core device component issues .................................................................................................. 917
Warn: '<command>' is not recognized as an internal or external command ............................. 917
Python script doesn't log messages .................................................................................. 917
AWS CLI issues ....................................................................................................................... 918
Error: Invalid choice: 'greengrassv2' ................................................................................... 918
Tag your resources .......................................................................................................................... 919
Using tags in AWS IoT Greengrass V2 ....................................................................................... 919
Tag with the AWS Management Console ........................................................................... 919
Tag with the AWS IoT Greengrass V2 API .......................................................................... 919
Using tags with IAM policies .................................................................................................... 920
Open source software ..................................................................................................................... 921
Document history ........................................................................................................................... 922
AWS glossary ................................................................................................................................. 932
xv
AWS IoT Greengrass Developer Guide, Version 2
For first-time users
What is AWS IoT Greengrass?
AWS IoT Greengrass is an open source Internet of Things (IoT) edge runtime and cloud service that helps
you build, deploy and manage IoT applications on your devices. You can use AWS IoT Greengrass to build
software that enables your devices to act locally on the data that they generate, run predictions based
on machine learning models, and filter and aggregate device data. AWS IoT Greengrass enables your
devices to collect and analyze data closer to where that data is generated, react autonomously to local
events, and communicate securely with other devices on the local network. Greengrass devices can also
communicate securely with AWS IoT Core and export IoT data to the AWS Cloud. You can use AWS IoT
Greengrass to build edge applications using pre-built software modules, called components, that can
connect your edge devices to AWS services or third-party services. You can also use AWS IoT Greengrass
to package and run your software using Lambda functions, Docker containers, native operating system
processes, or custom runtimes of your choice.
The following example shows how an AWS IoT Greengrass device interacts with the AWS Cloud.
For first-time users of AWS IoT Greengrass
If you're new to AWS IoT Greengrass, we recommend that you review the following section:
• How AWS IoT Greengrass works (p. 2)
Next, follow the getting started tutorial (p. 31) to try out the basic features of AWS IoT Greengrass.
In this tutorial, you install the AWS IoT Greengrass Core software on a device, develop a Hello World
component, and package that component for deployment.
For existing users of AWS IoT Greengrass
For current users of AWS IoT Greengrass, we recommend the following topics to help you understand the
new features in AWS IoT Greengrass Version 2, and learn how to move from version 1 to version 2:
• What's new in AWS IoT Greengrass Version 2 (p. 12)
• Move from AWS IoT Greengrass Version 1 (p. 8)
1
AWS IoT Greengrass Developer Guide, Version 2
How AWS IoT Greengrass works
How AWS IoT Greengrass works
The AWS IoT Greengrass client software, also called AWS IoT Greengrass Core software, runs on Linux-
based distributions, such as Ubuntu or Raspberry Pi OS, for devices with ARM or x86 architectures. With
AWS IoT Greengrass, you can program devices to act locally on the data they generate, run predictions
based on machine learning models, and filter and aggregate device data. AWS IoT Greengrass enables
local execution of AWS Lambda functions, Docker containers, native OS processes, or custom runtimes of
your choice.
AWS IoT Greengrass provides pre-built software modules called components that let you easily extend
edge device functionality. AWS IoT Greengrass components enable you to connect to AWS services
and third-party applications at the edge. After you develop your IoT applications, AWS IoT Greengrass
enables you to remotely deploy, configure, and manage those applications on your fleet of devices in the
field.
The following example shows how an AWS IoT Greengrass device interacts with the AWS IoT Greengrass
cloud service and other AWS services in the AWS Cloud.
Key concepts for AWS IoT Greengrass
The following are essential concepts for understanding and using AWS IoT Greengrass:
Greengrass core device
A device that runs the AWS IoT Greengrass Core software. A Greengrass core device is an AWS
IoT thing. You can add multiple core devices to AWS IoT thing groups to create and manage
groups of Greengrass core devices. For more information, see Setting up AWS IoT Greengrass core
devices (p. 62).
Greengrass client device
A device that connects to and communicates with a Greengrass core device over MQTT. A Greengrass
client device is an AWS IoT thing. The core device can process, filter, and aggregate data from client
2
AWS IoT Greengrass Developer Guide, Version 2
Key concepts
devices that connect to it. You can configure the core device to relay MQTT messages between client
devices, the AWS IoT Core cloud service, and Greengrass components. For more information, see
Interact with local IoT devices (p. 638).
Client devices can run FreeRTOS or use the AWS IoT Device SDK or Greengrass discovery
API (p. 664) to get information about core devices to which they can connect.
Greengrass component
A software module that is deployed to and runs on a Greengrass core device. All software that is
developed and deployed with AWS IoT Greengrass is modeled as a component. AWS IoT Greengrass
provides pre-built public components that provide features and functionality that you can use in
your applications. You can also develop your own custom components, on your local device or in the
cloud. After you develop a custom component, you can use the AWS IoT Greengrass cloud service
to deploy it to single or multiple core devices. You can create a custom component and deploy that
component to a core device. When you do, the core device downloads the following resources to run
the component:
• Recipe: A JSON or YAML file that describes the software module by defining component details,
configuration, and parameters.
• Artifact: The source code, binaries, or scripts that define the software that will run on your device.
You can create artifacts from scratch, or you can create a component using a Lambda function, a
Docker container, or a custom runtime.
• Dependency: The relationship between components that enables you to enforce automatic
updates or restarts of dependent components. For example, you can have a secure message
processing component dependent on an encryption component. This ensures that any updates to
the encryption component automatically update and restart the message processing component.
For more information, see AWS-provided components (p. 175) and Develop AWS IoT Greengrass
components (p. 440).
Deployment
The process to send components and apply the desired component configuration to a destination
target device, which can be a single Greengrass core device or a group of Greengrass core devices.
Deployments automatically apply any updated component configurations to the target and include
any other components that are defined as dependencies. You can also clone an existing deployment
to create a new deployment that uses the same components but is deployed to a different target.
Deployments are continuous, which means that any updates you make to the components or the
component configuration of a deployment automatically get sent to all destination targets. For
more information, see Deploy AWS IoT Greengrass components to devices (p. 491).
AWS IoT Greengrass Core software
The set of all AWS IoT Greengrass software that you install on a core device. AWS IoT Greengrass
Core software comprises the following:
• Nucleus: This required component provides the minimum functionality of the AWS IoT Greengrass
Core software. The nucleus manages deployments, orchestration, and lifecycle management of
other components. It also facilitates communication between AWS IoT Greengrass components
locally on an individual device. For more information, see Greengrass nucleus (p. 181).
• Optional components: These configurable components are provided by AWS IoT Greengrass and
enable additional features on your edge devices. Depending on your requirements, you can choose
the optional components that you want to deploy to your device, such as data streaming, local
machine learning inference, or a local command line interface. For more information, see AWS-
provided components (p. 175).
You can upgrade your AWS IoT Greengrass Core software by deploying new versions of your
components to your device.
3
AWS IoT Greengrass Developer Guide, Version 2
Features of AWS IoT Greengrass
Features of AWS IoT Greengrass
AWS IoT Greengrass Version 2 consists of the following elements:
• Software distributions
• The Greengrass nucleus component, which is the minimum installation of the AWS IoT Greengrass
Core software. This component manages deployments, orchestration, and lifecycle management of
Greengrass components.
• Additional optional components provided by AWS that integrate with services, protocols, and
software.
• The AWS IoT Device SDK, which contains the interprocess communication (IPC) SDK and the
Greengrass discovery SDK for client devices.
• The Stream Manager SDK.
• Cloud service
• AWS IoT Greengrass V2 API
• AWS IoT Greengrass V2 console
AWS IoT Greengrass Core software
You can use the AWS IoT Greengrass Core software that runs on your edge devices to do the following:
• Process data streams on the local device with automatic exports to the AWS Cloud. For more
information, see Manage data streams on the AWS IoT Greengrass Core (p. 682).
• Support MQTT messaging between AWS IoT and components. For more information, see Publish/
subscribe AWS IoT Core MQTT messages (p. 586).
• Interact with local devices that connect and communicate over MQTT. For more information, see
Interact with local IoT devices (p. 638).
• Support local publish and subscribe messaging between components. For more information, see
Publish/subscribe local messages (p. 561).
• Deploy and invoke components and Lambda functions. For more information, see Deploy AWS IoT
Greengrass components to devices (p. 491).
• Manage component lifecycles, such as with support for install and run scripts. For more information,
see AWS IoT Greengrass component recipe reference (p. 471).
• Perform secure, over-the-air (OTA) software updates of the AWS IoT Greengrass Core software and
custom components. For more information, see Update the AWS IoT Greengrass Core software
(OTA) (p. 170) and Deploy AWS IoT Greengrass components to devices (p. 491).
• Provide secure, encrypted storage of local secrets and controlled access by components. For more
information, see Secret manager (p. 374).
• Secure connections between devices and the AWS Cloud with device authentication and authorization.
For more information, see Device authentication and authorization for AWS IoT Greengrass (p. 773).
You configure and manage Greengrass core devices through AWS IoT Greengrass APIs where you create
continuous software deployments. For more information, see Deploy AWS IoT Greengrass components to
devices (p. 491).
Some features are supported on only certain platforms. For more information, see Greengrass feature
compatibility by operating system (p. 5).
For more information about supported platforms, requirements, and downloads, see Setting up AWS IoT
Greengrass core devices (p. 62).
By downloading this software, you agree to the Greengrass Core Software License Agreement.
4
AWS IoT Greengrass Developer Guide, Version 2
Greengrass feature compatibility by operating system
Greengrass feature compatibility by operating
system
AWS IoT Greengrass supports devices that run various operating systems. Some features are supported
on only certain operating systems. Use the following tables to learn which features are available for each
supported operating system. For more information about supported operating systems, requirements,
and how to set up Greengrass core devices, see Setting up AWS IoT Greengrass core devices (p. 62).
Messaging
Feature Linux Windows
Exchange MQTT messages
between AWS IoT and Yes Yes
components
Exchange local publish/
subscribe messages between Yes Yes
components
Interact with local IoT devices
over MQTT Yes Yes
Interact with local Modbus-RTU
devices using the Modbus-RTU Yes No
component
Security
Feature Linux Windows
Secure connections with device
authentication and authorization Yes Yes
Deploy and access secure,
encrypted secrets from AWS Yes Yes
Secrets Manager
Audit core devices with AWS IoT
Device Defender Yes Yes
Use AWS credentials to interact
with AWS services Yes Yes
Installation
Feature Linux Windows
Install AWS IoT Greengrass with
automatic provisioning Yes Yes
Install AWS IoT Greengrass with
manual provisioning Yes Yes
5
AWS IoT Greengrass Developer Guide, Version 2
Greengrass feature compatibility by operating system
Feature Linux Windows
Install AWS IoT Greengrass with
AWS IoT fleet provisioning Yes Yes
Install AWS IoT Greengrass with
custom provisioning plugins Yes Yes
Run AWS IoT Greengrass in
a Docker container using a Yes No
prebuilt Docker image
Remote maintenance and updates
Feature Linux Windows
Perform secure, over-the-air
(OTA) software updates Yes Yes
Manage core devices with AWS
Systems Manager Yes No
Connect to core devices with
AWS IoT secure tunneling Yes No
Machine learning
Feature Linux Windows
Perform machine learning
inference using Amazon Yes Yes
SageMaker Edge Manager
Perform machine learning
inference using DLR Yes Yes
Perform machine learning
inference using TensorFlow Yes Yes
Component features
Feature Linux Windows
Deploy and invoke Lambda
functions Yes No
Run Docker containers in
components Yes Yes
Process and export high-volume
data streams using stream Yes Yes
manager
Manage component lifecycles
with lifecycle scripts Yes Yes
6
AWS IoT Greengrass Developer Guide, Version 2
Greengrass feature compatibility by operating system
Feature Linux Windows
Interact with device shadows Yes Yes
Upload logs to Amazon
CloudWatch Logs Yes Yes
Upload data to Amazon
CloudWatch metrics using the Yes Yes
CloudWatch metrics component
Publish messages to Amazon
Simple Notification Service using Yes No
the Amazon SNS component
Publish data to Amazon Kinesis
Data Firehose delivery streams Yes Yes
using stream manager
Publish data to Amazon Kinesis
Data Firehose delivery streams
using the Kinesis Data Firehose Yes No
component
Gather and act on real-time
system telemetry metrics Yes Yes
Configure system resource limits
for component processes Yes No
Pause and resume component
processes Yes No
Integrate with AWS IoT SiteWise
using the AWS IoT SiteWise Yes No
components
Publish video streams to
Amazon Kinesis Video Streams
using the edge connector Yes No
for Kinesis Video Streams
component
Component development
Feature Linux Windows
Develop components locally on
core devices Yes Yes
Interact with a core device using
the AWS IoT Greengrass CLI Yes Yes
Interact with a core device using
the local debug console Yes Yes
Use the AWS IoT Device SDK for
Python in custom components Yes Yes
7
AWS IoT Greengrass Developer Guide, Version 2
Move from Version 1
Feature Linux Windows
Use the AWS IoT Device SDK for
C++ in custom components Yes Yes
Use the AWS IoT Device SDK for
Java in custom components Yes Yes
Device certification
Feature Linux Windows
Use AWS IoT Device Tester
for AWS IoT Greengrass V2 to Yes Yes
validate IoT devices
Move from AWS IoT Greengrass Version 1
AWS IoT Greengrass Version 2 is a new major version release of the AWS IoT Greengrass Core software,
APIs, and console. You can't use the AWS IoT Greengrass Core software v1.x with the V2 APIs. Likewise,
you can't use the AWS IoT Greengrass Core software v2.0 with the V1 APIs. However, by using some
modifications, you can run your V1 applications on AWS IoT Greengrass V2.
Topics
• Differences between V1 and V2 (p. 8)
• Run AWS IoT Greengrass V1 applications on AWS IoT Greengrass V2 (p. 10)
Differences between V1 and V2
AWS IoT Greengrass V2 introduces new fundamental concepts for devices, fleets, and deployable
software. This section describes the V1 concepts that are different in V2.
• AWS IoT Greengrass groups and deployments
In AWS IoT Greengrass V1, a group defines a core device, the settings and software for that core
device, and the list of AWS IoT things that connect to that core device.
In AWS IoT Greengrass V2, you use deployments to define the software components and configurations
that run on core devices. Each deployment targets a single core device or an AWS IoT thing group that
can contain multiple core devices. Deployments to thing groups are continuous, so when you add a
core device to a thing group, it receives the software configuration for that fleet. For more information,
see Deploy AWS IoT Greengrass components to devices (p. 491).
You can also create local deployments to develop and test custom software components. For more
information, see Create AWS IoT Greengrass components (p. 442).
• AWS IoT Greengrass Core software and connectors
In AWS IoT Greengrass V1, the AWS IoT Greengrass Core software is a single package that contains the
software and all of its features. AWS IoT Greengrass connectors are modules that you deploy to AWS
IoT Greengrass V1 core devices.
In AWS IoT Greengrass V2, the AWS IoT Greengrass Core software is modular, so that you can choose
what to install to control the memory footprint. The Greengrass nucleus component (p. 181) is the
8
AWS IoT Greengrass Developer Guide, Version 2
Differences between V1 and V2
minimum required installation of the AWS IoT Greengrass Core software that handles deployments,
orchestration, and lifecycle management of other components. Features such as stream manager,
secret manager, and log manager are components that you deploy only when you need those features.
AWS IoT Greengrass V2 also provides some AWS IoT Greengrass V1 connectors as components. For
more information, see AWS-provided components (p. 175).
• AWS Lambda functions
In AWS IoT Greengrass V1, Lambda functions define the software that runs on core devices. In each
Greengrass group, you define subscriptions and local resources that the function uses. You also
define the container parameters for functions that the AWS IoT Greengrass Core software runs in a
containerized Lambda runtime environment.
In AWS IoT Greengrass V2, components are the software that run on core devices. Components can
consist of any software applications, and each component has a recipe that defines the component's
metadata, parameters, dependencies, and scripts to run at each step in the component lifecycle. The
recipe also defines the component's artifacts, which are binary files such as scripts, compiled code,
and static resources. When you deploy a component to a core device, the core device downloads the
component recipe and artifacts to run the component. For more information, see Develop AWS IoT
Greengrass components (p. 440).
You can import Lambda functions as components that run in a Lambda runtime environment in
AWS IoT Greengrass V2. When you import the Lambda function, you specify the subscriptions,
local resources, and container parameters for the function. For more information, see Run AWS IoT
Greengrass V1 applications on AWS IoT Greengrass V2 (p. 10)..
• Subscriptions
In AWS IoT Greengrass V1, subscriptions specify where Lambda functions receive event messages to
consume as function payloads. Functions subscribe to local publish/subscribe messages and AWS IoT
Core MQTT messages.
In AWS IoT Greengrass V2, components manage their own subscriptions to local publish/subscribe and
AWS IoT Core MQTT messages. In the component recipe, you define authorization policies to specify
which topics the component can use to communicate. In component code, you can use interprocess
communication (IPC) for local publish/subscribe messaging and AWS IoT Core MQTT messaging. For
more information, see Use the AWS IoT Device SDK to communicate with the Greengrass nucleus,
other components, and AWS IoT Core (p. 545).
• Local resources
In AWS IoT Greengrass V1, Lambda functions run in containers that you configure to access volumes
and devices on the core device's file system.
In AWS IoT Greengrass V2, components run outside containers, so you don't need to specify which
local resources the component can access. You can develop components that work directly with local
resources on core devices. You can also develop components that run Docker containers. For more
information, see Run a Docker container (p. 456).
Note
When you import a containerized Lambda function as a component, you specify the local
resources that the function uses.
• Greengrass devices (connected devices)
In AWS IoT Greengrass V1, Greengrass devices are AWS IoT things that you add to a Greengrass group
to connect to the core device in that group and communicate over MQTT. You must deploy that
group each time that you add or remove a connected device. You use subscriptions to relay messages
between connected devices, AWS IoT Core, and applications on the core device.
In AWS IoT Greengrass V2, connected devices are called Greengrass client devices, and you
associate client devices to core devices to connect them and communicate over MQTT. You can
9
AWS IoT Greengrass Developer Guide, Version 2
Run V1 applications on V2
define authorization policies that apply to groups of client devices, so you don't need to create a
deployment to add or remove a client device. To relay messages between client devices, AWS IoT
Core, and Greengrass components, you can configure an optional MQTT bridge component. For more
information, see Interact with local IoT devices (p. 638).
In both AWS IoT Greengrass V1 and AWS IoT Greengrass V2, devices can run FreeRTOS or use the AWS
IoT Device SDK or Greengrass discovery API (p. 664) to get information about core devices to which
they can connect.
• Local shadow service
In AWS IoT Greengrass V1, the local shadow service is enabled by default, and supports only unnamed
classic shadows. You use the Greengrass Core SDK in your Lambda functions to interact with shadows
on your devices.
In AWS IoT Greengrass V2, you enable the local shadow service by deploying the shadow manager
component. You can then use the AWS IoT Device SDK V2 in Lambda functions, or in custom
components, to interact with shadows on your devices.
In both AWS IoT Greengrass V1 and AWS IoT Greengrass V2, you can sync local shadow states with
cloud shadows in AWS IoT Core. For more information, see Interact with device shadows (p. 678).
Run AWS IoT Greengrass V1 applications on AWS IoT
Greengrass V2
You can run most AWS IoT Greengrass V1 applications on AWS IoT Greengrass V2. You can use AWS-
provided components that offer the same functionality as AWS IoT Greengrass connectors, and you can
import Lambda functions as components that run on AWS IoT Greengrass V2.
Topics
• Can I run my Greengrass v1.x applications on Greengrass v2.0? (p. 10)
• Run V1 Lambda functions (p. 11)
• Run AWS IoT Greengrass connectors (p. 12)
• Run machine learning inference (p. 12)
• Connect V1 Greengrass devices (p. 12)
Can I run my Greengrass v1.x applications on Greengrass v2.0?
AWS IoT Greengrass provides features that you can use to run your AWS IoT Greengrass Core software
v1.x applications on the AWS IoT Greengrass Core software v2.0. However, if your v1.x applications use
any of the following listed features, you won't be able to run them on the v2.0 software yet.
• Hardware security integration
• Stream manager telemetry metrics
• The following languages in the AWS IoT Greengrass Core SDK:
• Node.js
• C
• The C and C++ Lambda function runtimes.
You can develop custom components (p. 440) to build any feature or runtime to run on Greengrass core
devices.
10
AWS IoT Greengrass Developer Guide, Version 2
Run V1 applications on V2
Run V1 Lambda functions
You can import Lambda functions as AWS IoT Greengrass V2 components. If your components use
features such as stream manager or local secrets, you must define dependencies on the AWS-provided
components that package these features' functionality. When you deploy a component, the deployment
includes the component dependencies that you specify. You configure these dependent features when
you deploy your Lambda function component.
If your Lambda function uses features such as stream manager or local secrets, you must define
dependencies on the AWS-provided components that package these features. When you deploy the
Lambda function component, the deployment also includes the component for each feature that
you define as a dependency. In the deployment, you can configure parameters such as which secrets
to deploy to the core device. Not all V1 features require a component dependency for your Lambda
function on V2. The following list describes how to use V1 features on V2 in your Lambda function
component.
• Stream manager
If your Lambda function uses stream manager, specify aws.greengrass.StreamManager as
a component dependency when you import the function. When you deploy the stream manager
component, specify the stream manager parameters to set for the target core devices. For more
information, see Stream manager (p. 398).
• Local secrets
If your Lambda function uses local secrets, specify aws.greengrass.SecretManager as a
component dependency when you import the function. When you deploy the secret manager
component, specify the secret resources to deploy to the target core devices. The core device's role
alias must point to an IAM role that allows the core device to retrieve the secret resources to deploy.
For more information, see Secret manager (p. 374).
•
Subscriptions
If your Lambda function publishes messages to the local publish/subscribe broker or to AWS IoT
Core, specify aws.greengrass.LegacySubscriptionRouter as a component dependency
when you import the function. When you deploy the legacy subscription router component, specify
the subscriptions that the Lambda function uses. For more information, see Legacy subscription
router (p. 260).
Note
This component is required only if your Lambda function uses the publish() function
in the AWS IoT Greengrass Core SDK. If you update your Lambda function code to use the
interprocess communication (IPC)s interface in the V2 AWS IoT Device SDK, you don't need
to deploy the legacy subscription router component. For more information, see the following
interprocess communication (p. 545) services:
• Publish/subscribe local messages (p. 561)
• Publish/subscribe AWS IoT Core MQTT messages (p. 586)
• Local volumes and devices
If your containerized Lambda function accesses local volumes or devices, specify those volumes and
devices when you import the Lambda function. This feature doesn't require a component dependency.
• Local shadows
If your Lambda function interacts with local shadows, you must update the Lambda function code
to use the AWS IoT Device SDK V2. You must also specify aws.greengrass.ShadowManager as a
component dependency when you import the function.
• Access other AWS services
11
AWS IoT Greengrass Developer Guide, Version 2
What's new in Version 2
If your Lambda function uses AWS credentials to make requests to other AWS services, specify
aws.greengrass.TokenExchangeService as a component dependency when you import the
function. The core device's role alias must point to an IAM role that allows the core device to perform
the AWS operations that the Lambda function uses. For more information, see Token exchange
service (p. 407) and Authorize core devices to interact with AWS services (p. 790).
For more information, see Run AWS Lambda functions (p. 523).
Run AWS IoT Greengrass connectors
You can deploy AWS-provided components that offer the same functionality of AWS IoT Greengrass
connectors. When you create the deployment, you can configure the connectors' parameters. For more
information, see the following AWS IoT Greengrass V2 components that provide Greengrass connectors:
• CloudWatch metrics component (p. 201)
• AWS IoT Device Defender component (p. 230)
• Kinesis Data Firehose component (p. 244)
• Modbus-RTU protocol adapter component (p. 344)
• Amazon SNS component (p. 389)
AWS IoT Greengrass V2 doesn't provide a component to replace the Docker application deployment
connector, but you can create components that run Docker containers from images. For more
information, see Run a Docker container (p. 456).
Run machine learning inference
AWS IoT Greengrass V2 provides sample Amazon SageMaker Neo DLR machine learning components and
models. You can use these features for image classification and object detection. To use other machine
learning frameworks, such as MXNet and TensorFlow, you can develop your own custom components
that use these frameworks.
Connect V1 Greengrass devices
In AWS IoT Greengrass V2, Greengrass devices (or connected devices) are called client devices. AWS
IoT Greengrass V2 support for client devices is backward-compatible with AWS IoT Greengrass V1, so
you can connect V1 core devices to V2 core devices without changing their application code. To enable
client devices to connect a V2 core device, deploy Greengrass components that enable client device
support, and associate the client devices to the core device. To relay messages between client devices,
the AWS IoT Core cloud service, and Greengrass components (including Lambda functions), deploy and
configure the MQTT bridge component (p. 360). You can deploy the IP detector component (p. 240)
to automatically detect connectivity information, or you can manually manage endpoints. For more
information, see Interact with local IoT devices (p. 638).
What's new in AWS IoT Greengrass Version 2
AWS IoT Greengrass Version 2 is a new major version release of AWS IoT Greengrass that introduces the
following features:
• Open source edge runtime—The edge runtime is now open source and distributed under the Apache
2.0 license and available on GitHub. You can now view the AWS IoT Greengrass edge runtime code,
which allows you to troubleshoot interactions with your application and helps you build more reliable
12
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass Core v2.5.2 software update
and performant applications running on AWS IoT Greengrass. You can also customize and extend
the AWS IoT Greengrass edge runtime to meet your specific hardware and software needs. For more
information, see Open source AWS IoT Greengrass Core software (p. 921).
• Improved modularity—You can add or remove pre-built software components based on your use
cases, and your device CPU and memory resources. For example, you can choose to include only pre-
built AWS IoT Greengrass components, such as stream manager, when you need to process data
streams with your application. Or, you can include only machine learning components when you want
to perform machine learning inference locally on your devices. For more information, see Develop AWS
IoT Greengrass components (p. 440) and AWS-provided components (p. 175).
• New local development tools—AWS IoT Greengrass includes a new command line interface (CLI) that
enables you to locally develop and debug applications on your device. In addition, the new local debug
console helps you visually debug applications on your device. With these new capabilities, you can
develop and debug code on a test device before using the cloud to deploy to your production devices.
For more information, see Greengrass CLI (p. 225) and Local debug console (p. 265).
• Improved fleet deployment features—AWS IoT Greengrass is now integrated with AWS IoT thing
groups. This enables you to organize your devices in groups and manage application deployments
across your devices with features that control rollout rates, timeouts, and rollbacks. For more
information, see Deploy AWS IoT Greengrass components to devices (p. 491).
AWS IoT Greengrass release notes provide details about AWS IoT Greengrass releases—new features,
updates and improvements, and general fixes. AWS IoT Greengrass has the following types of releases:
• New feature releases for AWS IoT Greengrass
• AWS IoT Greengrass Core software updates
This section contains all of the AWS IoT Greengrass V2 release notes, latest first, and includes major
feature changes and significant bug fixes. For information about additional minor fixes, see the aws-
greengrass organization on GitHub.
Release notes
• Release: AWS IoT Greengrass Core v2.5.2 software update on December 3, 2021 (p. 13)
• Release: AWS IoT Greengrass Core v2.5.1 software update on November 23, 2021 (p. 14)
• Release: AWS IoT Greengrass Core v2.5.0 software update on November 12, 2021 (p. 15)
• Release: AWS IoT Greengrass Core v2.4.0 software update on August 3, 2021 (p. 18)
• Release: AWS IoT Greengrass Core v2.3.0 software update on June 29, 2021 (p. 20)
• Release: AWS IoT Greengrass Core v2.2.0 software update on June 18, 2021 (p. 21)
• Release: AWS IoT Greengrass Core v2.1.0 software update on April 26, 2021 (p. 23)
• Release: AWS IoT Greengrass Core v2.0.5 software update on March 09, 2021 (p. 28)
• Release: AWS IoT Greengrass Core v2.0.4 software update on February 04, 2021 (p. 29)
Release: AWS IoT Greengrass Core v2.5.2 software
update on December 3, 2021
This release provides version 2.5.2 of the Greengrass nucleus component.
Release date: December 3, 2021
Release details
• Public component updates (p. 14)
13
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass Core v2.5.1 software update
Public component updates
The following table lists AWS-provided components that include new and updated features.
Important
When you deploy a component, AWS IoT Greengrass installs the latest supported versions of
all component dependencies for that component. Because of this, new patch versions of AWS-
provided public components might be automatically deployed to your core devices if you add
new devices to a thing group, or you update the deployment that targets those devices. Some
automatic updates, such as a nucleus update, can cause your devices to restart unexpectedly.
To prevent unintended updates for a component that is running on your device, we recommend
that you directly include your preferred version of that component when you create a
deployment (p. 493). For more information about update behavior for AWS IoT Greengrass
Core software, see Update the AWS IoT Greengrass Core software (OTA) (p. 170).
Component Details
Greengrass Version 2.5.2 of the Greengrass nucleus (p. 181) is available.
nucleus
Bug fixes and improvements
• Fixes an issue where after the Greengrass nucleus updates, the Windows
service fails to start again after you stop it or reboot the device.
AWS IoT Device Version 3.0.1 of the AWS IoT Device Defender (p. 230) component is available.
Defender
This version of the AWS IoT Device Defender component expects different
configuration parameters than version 2.x. If you use a non-default configuration
for version 2.x, and you want to upgrade from v2.x to v3.x, you must update the
component's configuration. For more information, see AWS IoT Device Defender
component configuration (p. 235).
New features
• Adds support for core devices that run Windows.
• Changes the component type from Lambda component to generic
component. This component now no longer depends on the legacy
subscription router component to create subscriptions.
• Adds the new UseInstaller configuration parameter that lets
you optionally disable the installation script that installs component
dependencies.
Release: AWS IoT Greengrass Core v2.5.1 software
update on November 23, 2021
This release provides version 2.5.1 of the Greengrass nucleus component.
Release date: November 23, 2021
Release details
• Public component updates (p. 14)
Public component updates
The following table lists AWS-provided components that include new and updated features.
14
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass Core v2.5.0 software update
Important
When you deploy a component, AWS IoT Greengrass installs the latest supported versions of
all component dependencies for that component. Because of this, new patch versions of AWS-
provided public components might be automatically deployed to your core devices if you add
new devices to a thing group, or you update the deployment that targets those devices. Some
automatic updates, such as a nucleus update, can cause your devices to restart unexpectedly.
To prevent unintended updates for a component that is running on your device, we recommend
that you directly include your preferred version of that component when you create a
deployment (p. 493). For more information about update behavior for AWS IoT Greengrass
Core software, see Update the AWS IoT Greengrass Core software (OTA) (p. 170).
Component Details
Greengrass Version 2.5.1 of the Greengrass nucleus (p. 181) is available.
nucleus
Bug fixes and improvements
• Adds support for 32-bit versions of the Java Runtime Environment (JRE) on
Windows.
• Changes thing group removal behavior for core
devices whose AWS IoT policy doesn't grant the
greengrass:ListThingGroupsForCoreDevice permission. With
this version, the deployment continues, logs a warning, and doesn't
remove components when you remove the core device from a thing group.
For more information, see Deploy AWS IoT Greengrass components to
devices (p. 491).
• Fixes an issue with system environment variables that the Greengrass
nucleus makes available to Greengrass component processes. You can now
restart a component for it to use the latest system environment variables.
Release: AWS IoT Greengrass Core v2.5.0 software
update on November 12, 2021
This release provides version 2.5.0 of the Greengrass nucleus component, new AWS-provided
components, and updates to AWS-provided components.
Release date: November 12, 2021
Release highlights
• Windows device support—You can now run the AWS IoT Greengrass Core software on devices
running Windows operating systems. For more information, see Supported platforms and
requirements (p. 62) and Greengrass feature compatibility by operating system (p. 5).
• New thing group removal behavior—You can now remove a core device from a thing group to
remove that thing group's components in the next deployment to that device.
Important
As a result of this change, a core device's AWS IoT policy must have the
greengrass:ListThingGroupsForCoreDevice permission. If you used the AWS IoT
Greengrass Core software installer to provision resources (p. 69), the default AWS IoT
policy allows greengrass:*, which includes this permission. For more information, see
Device authentication and authorization for AWS IoT Greengrass (p. 773).
• HTTPS proxy support—You can now configure the AWS IoT Greengrass Core software to connect
through HTTPS proxies. For more information, see Connect on port 443 or through a network
proxy (p. 165).
15
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass Core v2.5.0 software update
Release details
• Platform support updates (p. 16)
• Public component updates (p. 16)
Platform support updates
Platform Details
Windows AWS IoT Greengrass now supports running the AWS IoT Greengrass Core software
on the following versions of Windows:
• Windows 10
• Windows Server 2019
For more information, see Supported platforms and requirements (p. 62) and
Greengrass feature compatibility by operating system (p. 5).
Public component updates
The following table lists AWS-provided components that include new and updated features.
Important
When you deploy a component, AWS IoT Greengrass installs the latest supported versions of
all component dependencies for that component. Because of this, new patch versions of AWS-
provided public components might be automatically deployed to your core devices if you add
new devices to a thing group, or you update the deployment that targets those devices. Some
automatic updates, such as a nucleus update, can cause your devices to restart unexpectedly.
To prevent unintended updates for a component that is running on your device, we recommend
that you directly include your preferred version of that component when you create a
deployment (p. 493). For more information about update behavior for AWS IoT Greengrass
Core software, see Update the AWS IoT Greengrass Core software (OTA) (p. 170).
Component Details
Greengrass Version 2.5.0 of the Greengrass nucleus (p. 181) is available.
nucleus
New features
• Adds support for core devices that run Windows.
• Change the behavior of thing group removal. With this version, you can
remove a core device from a thing group to uninstall that thing group's
components in the next deployment.
As a result of this change, a core device's AWS IoT policy must have
the greengrass:ListThingGroupsForCoreDevice permission. If
you used the AWS IoT Greengrass Core software installer to provision
resources (p. 69), the default AWS IoT policy allows greengrass:*,
which includes this permission. For more information, see Device
authentication and authorization for AWS IoT Greengrass (p. 773).
• Adds support for HTTPS proxy configurations. For more information, see
Connect on port 443 or through a network proxy (p. 165).
• Adds the new windowsUser configuration parameter. You can use this
parameter to specify the default user to use to run components on a
16
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass Core v2.5.0 software update
Component Details
Windows core device. For more information, see Configure the user that
runs components (p. 161).
• Adds the new httpClient configuration options that you can use to
customize HTTP request timeouts to improve performance on slow
networks. For more information, see the httpClient (p. 188) configuration
parameter.
Bug fixes and improvements
• Fixes the bootstrap lifecycle option to restart the core device from a
component.
• Adds support for hyphens in recipe variables.
• Fixes IPC authorization for on-demand Lambda function components.
• Improves log messages and changes non-critical logs from INFO to DEBUG
level, so logs are more useful.
• Removes the iot:DescribeCertificate permission from the default
token exchange role (p. 790) that the Greengrass nucleus creates
when you install the AWS IoT Greengrass Core software with automatic
provisioning (p. 69). This permission isn't used by the Greengrass
nucleus.
• Fixes an issue so that the automatic provisioning script doesn't require the
iam:GetPolicy permission if iam:CreatePolicy is available for the
same policy.
• Additional minor fixes and improvements.
Greengrass CLI Version 2.5.0 of the Greengrass CLI (p. 225) is available.
New features
• Adds support for core devices that run Windows.
• Adds the new AuthorizedWindowsGroups configuration parameter that
you can specify to authorize system groups to use the Greengrass CLI on
Windows devices.
• Adds the windowsUser parameter for local deployments. You can use this
parameter specify the user to use to run components on a Windows core
device.
17
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass Core v2.4.0 software update
Component Details
CloudWatch Version 3.0.0 of the CloudWatch metrics (p. 201) component is available.
metrics
This version of the CloudWatch metrics component expects different
configuration parameters than version 2.x. If you use a non-default configuration
for version 2.x, and you want to upgrade from v2.x to v3.x, you must update
the component's configuration. For more information, see CloudWatch metrics
component configuration (p. 207).
New features
• Adds support for core devices that run Windows.
• Changes the component type from Lambda component to generic
component. This component now no longer depends on the legacy
subscription router component to create subscriptions.
• Adds new InputTopic configuration parameter to specify the topic to
which the component subscribes to receive messages.
• Adds new OutputTopic configuration parameter to specify the topic to
which the component publishes status responses.
• Adds new PubSubToIoTCore configuration parameter to specify whether
to publish and subscribe to AWS IoT Core MQTT topics.
• Adds the new UseInstaller configuration parameter that lets
you optionally disable the installation script that installs component
dependencies.
Bug fixes and improvements
Adds support for duplicate timestamps in input data.
Lambda manager Version 2.2.0 of the Lambda manager (p. 255) component is available.
Bug fixes and improvements
• Fixes an issue where Lambda functions couldn't write logs after a restart.
• Fixes an issue where the legacy subscription router sends duplicate
messages when there are wildcards in the topic.
• Fixes an issue where non-pinned Lambda functions couldn't use the
Greengrass interprocess communication (IPC) library in the AWS IoT Device
SDK.
Release: AWS IoT Greengrass Core v2.4.0 software
update on August 3, 2021
This release provides version 2.4.0 of the Greengrass nucleus component, new AWS-provided
components, and updates to AWS-provided components.
Release date: August 3, 2021
Release highlights
• System resource limits—The Greengrass nucleus component now supports system resource
limits. You can configure the maximum amount of CPU and RAM usage that each component's
processes can use on the core device. For more information, see Configure system resource limits for
components (p. 164).
18
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass Core v2.4.0 software update
• Pause/resume components—The Greengrass nucleus now supports pausing and resuming
components. You can use the interprocess communication (IPC) library to develop custom
components that pause and resume other components' processes. For more information, see
PauseComponent (p. 605) and ResumeComponent (p. 605).
• Install with AWS IoT fleet provisioning—Use the new AWS IoT fleet provisioning plugin to install
the AWS IoT Greengrass Core software on devices that connect to AWS IoT to provision required AWS
resources. Devices use a claim certificate to provision. You can embed the claim certificate on devices
during manufacturing, so each device can provision as soon as it comes online. For more information,
see Install AWS IoT Greengrass Core software with AWS IoT fleet provisioning (p. 92).
• Install with custom provisioning—Develop a custom provisioning plugin to provision required
AWS resources when you install the AWS IoT Greengrass Core software on devices. You can create
a Java application that runs during installation to set up Greengrass core devices for your custom
use case. For more information, see Install AWS IoT Greengrass Core software with custom resource
provisioning (p. 117).
Release details
• Public component updates (p. 19)
Public component updates
The following table lists AWS-provided components that include new and updated features.
Important
When you deploy a component, AWS IoT Greengrass installs the latest supported versions of
all component dependencies for that component. Because of this, new patch versions of AWS-
provided public components might be automatically deployed to your core devices if you add
new devices to a thing group, or you update the deployment that targets those devices. Some
automatic updates, such as a nucleus update, can cause your devices to restart unexpectedly.
To prevent unintended updates for a component that is running on your device, we recommend
that you directly include your preferred version of that component when you create a
deployment (p. 493). For more information about update behavior for AWS IoT Greengrass
Core software, see Update the AWS IoT Greengrass Core software (OTA) (p. 170).
Component Details
Greengrass Version 2.4.0 of the Greengrass nucleus (p. 181) is available.
nucleus
New features
• Adds support for system resource limits. You can configure the maximum
amount of CPU and RAM usage that each component's processes can use
on the core device. For more information, see Configure system resource
limits for components (p. 164).
• Adds IPC operations to pause and resume components.
For more information, see PauseComponent (p. 605) and
ResumeComponent (p. 605).
• Adds support for provisioning plugins. You can specify a JAR file to run
during installation to provision required AWS resources for a Greengrass
core device. The Greengrass nucleus includes an interface that you can
implement to develop custom provisioning plugins. For more information,
see Install AWS IoT Greengrass Core software with custom resource
provisioning (p. 117).
• Adds the optional thing-name-policy argument to the AWS IoT
Greengrass Core software installer. You can use this option to specify an
19
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass Core v2.3.0 software update
Component Details
existing or custom AWS IoT policy when you install the AWS IoT Greengrass
Core software with automatic resource provisioning (p. 69).
Bug fixes and improvements
• Updates logging configuration on startup. This fixes an issue where the
logging configuration wasn't applied on startup.
• Updates the nucleus loader symlink to point to the component store in
the Greengrass root folder during installation. This update enables you to
delete the JAR file and other nucleus artifacts that you download when you
install the AWS IoT Greengrass Core software.
• Additional minor fixes and improvements. For more information, see the
changelog on GitHub.
Greengrass CLI Version 2.4.0 of the Greengrass CLI (p. 225) is available.
New features
• Adds support for system resource limits. When you create a local
deployment, you can configure the maximum amount of CPU and
RAM usage that each component's processes can use on the core
device. For more information, see Configure system resource limits for
components (p. 164) and the deployment create command (p. 434).
AWS IoT fleet The AWS IoT fleet provisioning by claim plugin is now available. For more
provisioning by information, see Install AWS IoT Greengrass Core software with AWS IoT fleet
claim provisioning (p. 92).
New features
• Adds support to install the AWS IoT Greengrass Core software with AWS
IoT fleet provisioning. During installation, devices connect to AWS IoT to
provision required AWS resources and download device certificates to use
for regular operations.
Release: AWS IoT Greengrass Core v2.3.0 software
update on June 29, 2021
This release provides version 2.3.0 of the Greengrass nucleus component.
Release date: June 29, 2021
Release highlights
• Large configuration support—The Greengrass nucleus component now supports deployment
documents up to 10 MB. You can now deploy larger configuration updates to Greengrass components.
Note
To use this feature, a core device's AWS IoT policy must allow the
greengrass:GetDeploymentConfiguration permission. If you used the AWS IoT
Greengrass Core software installer to provision resources (p. 69), your core device's AWS
IoT policy allows greengrass:*, which includes this permission. For more information, see
Device authentication and authorization for AWS IoT Greengrass (p. 773).
Release details
• Public component updates (p. 21)
20
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass Core v2.2.0 software update
Public component updates
The following table lists AWS-provided components that include new and updated features.
Important
When you deploy a component, AWS IoT Greengrass installs the latest supported versions of
all component dependencies for that component. Because of this, new patch versions of AWS-
provided public components might be automatically deployed to your core devices if you add
new devices to a thing group, or you update the deployment that targets those devices. Some
automatic updates, such as a nucleus update, can cause your devices to restart unexpectedly.
To prevent unintended updates for a component that is running on your device, we recommend
that you directly include your preferred version of that component when you create a
deployment (p. 493). For more information about update behavior for AWS IoT Greengrass
Core software, see Update the AWS IoT Greengrass Core software (OTA) (p. 170).
Component Details
Greengrass Version 2.3.0 of the Greengrass nucleus (p. 181) is available.
nucleus
New features
• Adds support for deployment configuration documents up to 10 MB, up
from 7 KB (for deployments that target things) or 31 KB (for deployments
that target thing groups).
To use this feature, a core device's AWS IoT policy must allow the
greengrass:GetDeploymentConfiguration permission. If you
used the AWS IoT Greengrass Core software installer to provision
resources (p. 69), your core device's AWS IoT policy allows
greengrass:*, which includes this permission. For more information, see
Device authentication and authorization for AWS IoT Greengrass (p. 773).
• Adds the iot:thingName recipe variable. You can use this recipe variable
to get the name of the core device's AWS IoT thing in a recipe. For more
information, see Recipe variables (p. 484).
Bug fixes and improvements
• Additional minor fixes and improvements. For more information, see the
changelog on GitHub.
Release: AWS IoT Greengrass Core v2.2.0 software
update on June 18, 2021
This release provides version 2.2.0 of the Greengrass nucleus component, new AWS-provided
components, and updates to AWS-provided components.
Release date: June 18, 2021
Release highlights
• Client device support—The new AWS-provided client device components enable you to connect client
devices to your core devices using cloud discovery. You can sync client devices with AWS IoT Core and
interact with client devices in Greengrass components. For more information, see Interact with local
IoT devices (p. 638).
• Local shadow service—The new shadow manager component enables the local shadow service on
your core devices. You can use this shadow service to interact with local shadows while offline using
21
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass Core v2.2.0 software update
the Greengrass interprocess communication (IPC) libraries in the AWS IoT Device SDK. You can also
use the shadow manager component to synchronize local shadow states with AWS IoT Core. For more
information, see Interact with device shadows (p. 678).
Release details
• Public component updates (p. 22)
Public component updates
The following table lists AWS-provided components that include new and updated features.
Important
When you deploy a component, AWS IoT Greengrass installs the latest supported versions of
all component dependencies for that component. Because of this, new patch versions of AWS-
provided public components might be automatically deployed to your core devices if you add
new devices to a thing group, or you update the deployment that targets those devices. Some
automatic updates, such as a nucleus update, can cause your devices to restart unexpectedly.
To prevent unintended updates for a component that is running on your device, we recommend
that you directly include your preferred version of that component when you create a
deployment (p. 493). For more information about update behavior for AWS IoT Greengrass
Core software, see Update the AWS IoT Greengrass Core software (OTA) (p. 170).
Component Details
Greengrass Version 2.2.0 of the Greengrass nucleus (p. 181) is available.
nucleus
New features
• Adds IPC operations for local shadow management.
Bug fixes and improvements
• Reduces the size of the JAR file.
• Reduces memory usage.
• Fixes issues where the log configuration wasn't updated in certain cases.
• Additional minor fixes and improvements. For more information, see the
changelog on GitHub.
Shadow manager Version 2.0.0 of the new shadow manager component (p. 383) is available.
New features
• Adds support for classic and named shadows.
• Adds support for local shadow management using IPC.
• Adds support for shadow synchronization with AWS IoT Core.
Client device auth Version 2.0.0 of the new client device auth component (p. 194) is available.
New features
• Adds support for Greengrass client devices, which are local IoT devices that
connect to a core device over MQTT.
• Adds support for authentication and authorization of client devices and
their MQTT actions.
Moquette MQTT Version 2.0.0 of the new Moquette MQTT broker component (p. 365) is
broker available.
22
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass Core v2.1.0 software update
Component Details
New features
• Adds support for a local Moquette MQTT broker that handles
communication with client devices.
MQTT bridge Version 2.0.0 of the new MQTT bridge component (p. 360) is available.
New features
• Adds support to relay messages between the local MQTT broker, the local
Greengrass publish/subscribe broker, and the AWS IoT Core MQTT broker.
IP detector Version 2.0.0 of the new IP detector component (p. 240) is available.
New features
• Adds support to report a core device's local MQTT broker endpoints to the
AWS IoT Greengrass cloud service for client devices to connect.
Log manager Version 2.1.1 of the log manager component (p. 273) is available.
Bug fixes and improvements
• Fixes an issue where the system log configuration wasn't updated in certain
cases.
DLR object Version 2.1.2 of the DLR object detection (p. 306) is available.
detection
Bug fixes and improvements
• Fixes an image scaling issue that resulted in inaccurate bounding boxes in
the sample DLR object detection inference results.
TensorFlow Lite Version 2.1.1 of the TensorFlow Lite object detection (p. 329) is available.
object detection
Bug fixes and improvements
• Fixes an image scaling issue that resulted in inaccurate bounding boxes in
the sample TensorFlow Lite object detection inference results.
Release: AWS IoT Greengrass Core v2.1.0 software
update on April 26, 2021
This release provides version 2.1.0 of the Greengrass nucleus component and updates AWS-provided
components.
Release date: April 26, 2021
Release highlights
• Docker Hub and Amazon Elastic Container Registry (Amazon ECR) integration—The new Docker
application manager component enables you to download public or private images from Amazon ECR.
You can also use this component to download public images from Docker Hub and AWS Marketplace.
For more information, see Run a Docker container (p. 456).
• Dockerfile and Docker images for AWS IoT Greengrass Core software—You can use the Greengrass
Docker image to run AWS IoT Greengrass in a Docker container that uses Amazon Linux 2 as the
base operating system. You can also use the AWS IoT Greengrass Dockerfile to build your own
Greengrass image. For more information, see Run AWS IoT Greengrass Core software in a Docker
container (p. 131).
23
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass Core v2.1.0 software update
• Support for additional machine learning frameworks and platforms—You can deploy sample
machine learning inference components that use pre-trained models to perform sample image
classification and object detection using TensorFlow Lite 2.5.0 and DLR 1.6.0. This release also extends
sample machine learning support for Armv8 (AArch64) devices. For more information, see Perform
machine learning inference (p. 723).
Release details
• Platform support updates (p. 24)
• Public component updates (p. 24)
Platform support updates
Platform Details
Docker A Dockerfile and Docker image for AWS IoT Greengrass are now available.
Dockerfile
AWS IoT Greengrass provides a Dockerfile to build a container image that
has AWS IoT Greengrass Core software and dependencies installed on an
Amazon Linux 2 (x86_64) base image. You can modify the base image in the
Dockerfile to run AWS IoT Greengrass on a different platform architecture.
Docker image
AWS IoT Greengrass provides a pre-built Docker image that has AWS IoT
Greengrass Core software and dependencies installed on an Amazon Linux 2
(x86_64) base image.
For more information, see Run AWS IoT Greengrass Core software in a Docker
container (p. 131).
Public component updates
The following table lists AWS-provided components that include new and updated features.
Important
When you deploy a component, AWS IoT Greengrass installs the latest supported versions of
all component dependencies for that component. Because of this, new patch versions of AWS-
provided public components might be automatically deployed to your core devices if you add
new devices to a thing group, or you update the deployment that targets those devices. Some
automatic updates, such as a nucleus update, can cause your devices to restart unexpectedly.
To prevent unintended updates for a component that is running on your device, we recommend
that you directly include your preferred version of that component when you create a
deployment (p. 493). For more information about update behavior for AWS IoT Greengrass
Core software, see Update the AWS IoT Greengrass Core software (OTA) (p. 170).
Component Details
Greengrass Version 2.1.0 of the Greengrass nucleus (p. 181) is available.
nucleus
New features
• Supports downloading Docker images from private repositories in Amazon
ECR.
24
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass Core v2.1.0 software update
Component Details
• Adds the following parameters to customize the MQTT configuration on
core devices:
• maxInFlightPublishes – The maximum number of unacknowledged
MQTT QoS 1 messages that can be in flight at the same time.
• maxPublishRetry – The maximum number of times to retry a message
that fails to publish.
• Adds the fleetstatusservice configuration parameter to configure the
interval at which the core device publishes device status to the AWS Cloud.
• Additional minor fixes and improvements. For more information, see the
changelog on GitHub.
Bug fixes and improvements
• Fixes an issue that caused shadow deployments to be duplicated when the
nucleus restarts.
• Fixes an issue that caused the nucleus to crash when it encountered a
service load exception.
• Improves component dependency resolution to fail a deployment that
includes a circular dependency.
• Fixes an issue that prevented a plugin component from being redeployed if
that component had been previously removed from the core device.
• Fix an issue that caused the HOME environment variable to be set to
the /greengrass/v2/work directory for Lambda components or for
components that run as root. The HOME variable is now correctly set to the
home directory for the user that runs the component.
• Additional minor fixes and improvements. For more information, see the
changelog on GitHub.
Docker Version 2.0.0 of the new Docker application manager component (p. 216) is
application available.
manager
New features
• Manages credentials to download images from private repositories in
Amazon ECR.
• Downloads public images from Amazon ECR, Docker Hub, and AWS
Marketplace.
Lambda launcher Version 2.0.4 of the Lambda launcher component (p. 252) is available.
Bug fixes and improvements
• Fixes an issue where the component doesn't correctly pass
AddGroupOwner to the Lambda function container.
Legacy Version 2.1.0 of the legacy subscription router component (p. 260) is available.
subscription
router Bug fixes and improvements
• Adds support to specify component names instead of ARNs for source
and target. If you specify a component name for a subscription, you don't
need to reconfigure the subscription each time the version of the Lambda
function changes.
25
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass Core v2.1.0 software update
Component Details
Local debug Version 2.1.0 of the local debug console component (p. 265) is available.
console
New features
• Uses HTTPS to secure your connection to the local debug console. HTTPS is
enabled by default.
Bug fixes and improvements
• You can dismiss flashbar messages in the configuration editor.
Log manager Version 2.1.0 of the log manager component (p. 273) is available.
Bug fixes and improvements
• Use defaults for logFileDirectoryPath and logFileRegex that work
for Greengrass components that print to standard output (stdout) and
standard error (stderr).
• Correctly route traffic through a configured network proxy when uploading
logs to CloudWatch Logs.
• Correctly handle colon characters (:) in log stream names. CloudWatch
Logs log stream names don't support colons.
• Simplify log stream names by removing thing group names from the log
stream.
• Remove an error log message that prints during normal behavior.
DLR image Version 2.1.1 of the DLR image classification (p. 299) component is available.
classification
New features
• Use Deep Learning Runtime v1.6.0.
• Add support for sample image classification on Armv8 (AArch64)
platforms. This extends machine learning support for Greengrass core
devices running NVIDIA Jetson, such as the Jetson Nano.
• Enable camera integration for sample inference. Use the new UseCamera
configuration parameter to enable the sample inference code to access the
camera on your Greengrass core device and run inference locally on the
captured image.
• Add support for publishing inference results to the AWS Cloud. Use the
new PublishResultsOnTopic configuration parameter to specify the
topic on which you want to publish results.
• Add the new ImageDirectory configuration parameter that enables you
to specify a custom directory for the image on which you want to perform
inference.
Bug fixes and improvements
• Write inference results to the component log file instead of a separate
inference file.
• Use the AWS IoT Greengrass Core software logging module to log
component output.
• Use the AWS IoT Device SDK to read the component configuration and
apply configuration changes.
26
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass Core v2.1.0 software update
Component Details
DLR object Version 2.1.1 of the DLR object detection (p. 306) component is available.
detection
New features
• Use Deep Learning Runtime v1.6.0.
• Add support for sample object detection on Armv8 (AArch64) platforms.
This extends machine learning support for Greengrass core devices running
NVIDIA Jetson, such as the Jetson Nano.
• Enable camera integration for sample inference. Use the new UseCamera
configuration parameter to enable the sample inference code to access the
camera on your Greengrass core device and run inference locally on the
captured image.
• Add support for publishing inference results to the AWS Cloud. Use the
new PublishResultsOnTopic configuration parameter to specify the
topic on which you want to publish results.
• Add the new ImageDirectory configuration parameter that enables you
to specify a custom directory for the image on which you want to perform
inference.
Bug fixes and improvements
• Write inference results to the component log file instead of a separate
inference file.
• Use the AWS IoT Greengrass Core software logging module to log
component output.
• Use the AWS IoT Device SDK to read the component configuration and
apply configuration changes.
DLR image Version 2.1.1 of the DLR image classification model store (p. 313) component is
classification available.
model store
New features
• Add a sample ResNet-50 image classification model for Armv8 (AArch64)
platforms. This extends machine learning support for Greengrass core
devices running NVIDIA Jetson, such as the Jetson Nano.
DLR object Version 2.1.1 of the DLR object detection model store (p. 316) component is
detection model available.
store
New features
• Add a sample YOLOv3 object detection model for Armv8 (AArch64)
platforms. This extends machine learning support for Greengrass core
devices running NVIDIA Jetson, such as the Jetson Nano.
DLR installer Version 1.6.1 of the DLR (p. 319) component is available.
New features
• Install Deep Learning Runtime v1.6.0 and its dependencies.
• Add support for installing DLR on Armv8 (AArch64) platforms. This extends
machine learning support for Greengrass core devices running NVIDIA
Jetson, such as the Jetson Nano.
Bug fixes and improvements
• Install the AWS IoT Device SDK in the virtual environment to read the
component configuration and apply configuration changes.
• Additional minor bug fixes and improvements.
27
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass Core v2.0.5 software update
Component Details
TensorFlow Version 2.1.0 of the new TensorFlow Lite image classification (p. 324)
Lite image component is available.
classification
New features
• Add support for sample image classification inference using TensorFlow
Lite.
TensorFlow Lite Version 2.1.0 of the new TensorFlow Lite object detection (p. 329) component is
object detection available.
New features
• Add support for sample object detection inference using TensorFlow Lite.
TensorFlow Version 2.1.0 of the new TensorFlow Lite image classification model
Lite image store (p. 334) component is available.
classification
model store New features
• Provide a pre-trained MobileNet v1 quantized model for sample image
classification inference using TensorFlow Lite.
TensorFlow Lite Version 2.1.0 of the new TensorFlow Lite object detection model store (p. 337)
object detection component is available.
model store
New features
• Provide a pre-trained Single Shot Detection (SSD) MobileNet model
trained on the COCO dataset for sample object detection inference using
TensorFlow Lite.
TensorFlow Lite Version 2.5.0 of the new TensorFlow Lite (p. 339) component is available.
New features
• Install TensorFlow Lite v1.6.0 and its dependencies in a virtual environment
on Armv7, Armv8 (AArch64), and x86_64 platforms.
Release: AWS IoT Greengrass Core v2.0.5 software
update on March 09, 2021
This release provides version 2.0.5 of the Greengrass nucleus component and updates AWS-provided
components. It fixes an issue with network proxy support and an issue with the Greengrass data plane
endpoint in AWS China Regions.
Release date: March 09, 2021
Public component updates
The following table lists AWS-provided components that include new and updated features.
Important
When you deploy a component, AWS IoT Greengrass installs the latest supported versions of
all component dependencies for that component. Because of this, new patch versions of AWS-
provided public components might be automatically deployed to your core devices if you add
new devices to a thing group, or you update the deployment that targets those devices. Some
automatic updates, such as a nucleus update, can cause your devices to restart unexpectedly.
28
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass Core v2.0.4 software update
To prevent unintended updates for a component that is running on your device, we recommend
that you directly include your preferred version of that component when you create a
deployment (p. 493). For more information about update behavior for AWS IoT Greengrass
Core software, see Update the AWS IoT Greengrass Core software (OTA) (p. 170).
Component Details
Greengrass Version 2.0.5 of the Greengrass nucleus (p. 181) is available.
nucleus
Bug fixes and improvements
• Correctly routes traffic through a configured network proxy when
downloading AWS-provided components.
• Use the correct Greengrass data plane endpoint in AWS China Regions.
Release: AWS IoT Greengrass Core v2.0.4 software
update on February 04, 2021
This release provides version 2.0.4 of the Greengrass nucleus component. It includes the new
greengrassDataPlanePort parameter to configure HTTPS communication over port 443 and fixes
bugs. The minimal IAM policy now requires the iam:GetPolicy and sts:GetCallerIdentity when
the AWS IoT Greengrass Core software installer is run with --provision true.
Release date: February 04, 2021
Public component updates
The following table lists AWS-provided components that include new and updated features.
Important
When you deploy a component, AWS IoT Greengrass installs the latest supported versions of
all component dependencies for that component. Because of this, new patch versions of AWS-
provided public components might be automatically deployed to your core devices if you add
new devices to a thing group, or you update the deployment that targets those devices. Some
automatic updates, such as a nucleus update, can cause your devices to restart unexpectedly.
To prevent unintended updates for a component that is running on your device, we recommend
that you directly include your preferred version of that component when you create a
deployment (p. 493). For more information about update behavior for AWS IoT Greengrass
Core software, see Update the AWS IoT Greengrass Core software (OTA) (p. 170).
Component Details
Greengrass Version 2.0.4 of the Greengrass nucleus (p. 181) is available.
nucleus
New features
• Enables HTTPS traffic over port 443. You can use the new
greengrassDataPlanePort configuration parameter for version 2.0.4
of the nucleus component to configure HTTPS communication to travel
over port 443 instead of the default port 8443. For more information, see
Configure HTTPS over port 443 (p. 167).
• Adds the work path recipe variable. You can use this recipe variable to get
the path to components' work folders, which you can use to share files
between components and their dependencies. For more information, see
the work path recipe variable (p. 485).
29
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass Core v2.0.4 software update
Component Details
Bug fixes and improvements
• Prevents the creation of the token exchange AWS Identity and Access
Management (IAM) role policy if a role policy already exists.
As a result of this change, the installer now requires the iam:GetPolicy
and sts:GetCallerIdentity when run with --provision true.
For more information, see Minimal IAM policy for installer to provision
resources (p. 793).
• Correctly handles the cancellation of a deployment that has not yet been
registered successfully.
• Updates the configuration to remove older entries with newer timestamps
when rolling back a deployment.
• Additional minor fixes and improvements. For more information, see the
changelog on GitHub.
30
AWS IoT Greengrass Developer Guide, Version 2
Prerequisites
Getting started with AWS IoT
Greengrass V2
You can complete this getting started tutorial to learn about the basic features of AWS IoT Greengrass
V2. In this tutorial, you do the following:
• Install and configure the AWS IoT Greengrass Core software on a Linux device, such as a Raspberry Pi,
or a Windows device. This device is a Greengrass core device.
• Develop a Hello World component on your Greengrass core device. Components are software modules
that run on Greengrass core devices.
• Upload that component to AWS IoT Greengrass V2 in the AWS Cloud.
• Deploy that component from the AWS Cloud to your Greengrass core device.
Note
This tutorial describes how to set up a development environment and explore the features
of AWS IoT Greengrass. For more information about how to set up and configure production
devices, see the following:
• Setting up AWS IoT Greengrass core devices (p. 62)
• Install the AWS IoT Greengrass Core software (p. 67)
You can expect to spend 20 to 30 minutes on this tutorial.
Prerequisites
To complete this getting started tutorial, you need the following:
• An AWS account. If you don't have one, see Step 1: Set up an AWS account (p. 32).
• The use of an AWS Region that supports AWS IoT Greengrass V2. For the list of supported Regions, see
AWS IoT Greengrass V2 endpoints and quotas in the AWS General Reference
• An AWS Identity and Access Management (IAM) user with administrator permissions.
• A Windows, macOS, or Unix-like development computer with an internet connection.
• A device to set up as a Greengrass core device, such as a Raspberry Pi with Raspberry Pi OS (previously
called Raspbian), or a Windows 10 device. You must have administrator permissions on this device, or
the ability to acquire administrator privileges, such as through sudo.
You can also choose to use a different device that meets the requirements to install and run the
AWS IoT Greengrass Core software and has an internet connection to the same network as your
development computer. For more information, see the environment setup information for your device
type in Setting up AWS IoT Greengrass core devices (p. 62).
If your development computer meets these requirements, you can set it up as your Greengrass core
device in this tutorial.
31
AWS IoT Greengrass Developer Guide, Version 2
Step 1: Set up an AWS account
• Python 3.5 or later installed for all users on the device and added to the PATH environment variable.
On Windows, you must also have the Python Launcher for Windows installed for all users.
Important
On Windows, Python doesn't install for all users by default. When you install Python, you
must customize the installation to configure it for the AWS IoT Greengrass Core software to
run Python scripts. For example, if you use the graphical Python installer, do the following:
1. Select Install launcher for all users (recommended).
2. Choose Customize installation.
3. Choose Next.
4. Select Install for all users.
5. Select Add Python to environment variables.
6. Choose Install.
For more information, see Using Python on Windows in the Python 3 documentation.
• AWS Command Line Interface (AWS CLI) installed and configured with credentials on your
development computer and on your device. Make sure you use the same AWS Region to configure the
AWS CLI on your development computer and on your device. To use AWS IoT Greengrass V2 with the
AWS CLI, you must have one of the following versions or later:
• Minimum AWS CLI V1 version: v1.18.197
• Minimum AWS CLI V2 version: v2.1.11
Tip
You can run the following command to check the version of the AWS CLI that you have.
aws --version
For more information, see Installing, updating, and uninstalling the AWS CLI and Configuring the AWS
CLI in the AWS Command Line Interface User Guide.
Note
If you use a Raspberry Pi or another 32-bit ARM device, install AWS CLI V1. AWS CLI V2
isn't available for 32-bit ARM devices. For more information, see Installing, updating, and
uninstalling the AWS CLI version 1.
Step 1: Set up an AWS account
If you do not have an AWS account, complete the following steps to create one.
To sign up for an AWS account
1. Open https://portal.aws.amazon.com/billing/signup.
2. Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call and entering a verification code on the
phone keypad.
To create an administrator user for yourself and add the user to an administrators group
(console)
1. Sign in to the IAM console as the account owner by choosing Root user and entering your AWS
account email address. On the next page, enter your password.
32
AWS IoT Greengrass Developer Guide, Version 2
Step 2: Set up your environment
Note
We strongly recommend that you adhere to the best practice of using the Administrator
IAM user that follows and securely lock away the root user credentials. Sign in as the root
user only to perform a few account and service management tasks.
2. In the navigation pane, choose Users and then choose Add user.
3. For User name, enter Administrator.
4. Select the check box next to AWS Management Console access. Then select Custom password, and
then enter your new password in the text box.
5. (Optional) By default, AWS requires the new user to create a new password when first signing in. You
can clear the check box next to User must create a new password at next sign-in to allow the new
user to reset their password after they sign in.
6. Choose Next: Permissions.
7. Under Set permissions, choose Add user to group.
8. Choose Create group.
9. In the Create group dialog box, for Group name enter Administrators.
10. Choose Filter policies, and then select AWS managed - job function to filter the table contents.
11. In the policy list, select the check box for AdministratorAccess. Then choose Create group.
Note
You must activate IAM user and role access to Billing before you can use the
AdministratorAccess permissions to access the AWS Billing and Cost Management
console. To do this, follow the instructions in step 1 of the tutorial about delegating access
to the billing console.
12. Back in the list of groups, select the check box for your new group. Choose Refresh if necessary to
see the group in the list.
13. Choose Next: Tags.
14. (Optional) Add metadata to the user by attaching tags as key-value pairs. For more information
about using tags in IAM, see Tagging IAM entities in the IAM User Guide.
15. Choose Next: Review to see the list of group memberships to be added to the new user. When you
are ready to proceed, choose Create user.
You can use this same process to create more groups and users and to give your users access to your AWS
account resources. To learn about using policies that restrict user permissions to specific AWS resources,
see Access management and Example policies.
Step 2: Set up your environment
Follow the steps in this section to set up a Linux or Windows device to use as your AWS IoT Greengrass
core device.
Set up a Linux device (Raspberry Pi)
These steps assume that you use a Raspberry Pi with Raspberry Pi OS. If you use a different device or
operating system, consult the relevant documentation for your device.
To set up a Raspberry Pi for AWS IoT Greengrass V2
1. Enable SSH on your Raspberry Pi to remotely connect to it. For more information, see SSH (Secure
shell) in the Raspberry Pi Documentation.
33
AWS IoT Greengrass Developer Guide, Version 2
Step 2: Set up your environment
2. Find the IP address of your Raspberry Pi to connect to it with SSH. To do so, you can run the
following command on your Raspberry Pi.
hostname -I
3. Connect to your Raspberry Pi with SSH.
On your development computer, run the following command. Replace username with the name of
the user to sign in, and replace pi-ip-address with the IP address that you found in the previous
step.
ssh username@pi-ip-address
The default Raspberry Pi user name and password are pi and raspberry, respectively.
Important
If your development computer uses an earlier version of Windows, you might not have the
ssh command, or you might have ssh but can't connect to your Raspberry Pi. To connect to
your Raspberry Pi, you can install and configure PuTTY, which is a no-cost, open source SSH
client. Consult the PuTTY documentation to connect to your Raspberry Pi.
4. Install the Java runtime, which AWS IoT Greengrass Core software requires to run. On your
Raspberry Pi, use the following commands to install Java 11.
sudo apt install default-jdk
When the installation completes, run the following command to verify that Java runs on your
Raspberry Pi.
java -version
The command prints the version of Java that runs on the device. The output might look similar to
the following example.
openjdk version "11.0.9.1" 2020-11-04
OpenJDK Runtime Environment (build 11.0.9.1+1-post-Debian-1deb10u2)
OpenJDK 64-Bit Server VM (build 11.0.9.1+1-post-Debian-1deb10u2, mixed mode)
Set up a Windows device
To set up a Windows device for AWS IoT Greengrass V2
1. Install the Java runtime, which AWS IoT Greengrass Core software requires to run. We recommend
that you use Amazon Corretto 11 or OpenJDK 11..
2. Open the Windows Command Prompt (cmd.exe) as an administrator.
3. Create the default user in the LocalSystem account on the Windows device. Replace password with
a secure password.
net user /add ggc_user password
4. Download and install the PsExec utility from Microsoft on the device.
5. Use the PsExec utility to store the user name and password for the default user in the Credential
Manager instance for the LocalSystem account. Replace password with the user's password that you
set earlier.
34
AWS IoT Greengrass Developer Guide, Version 2
Step 3: Install the AWS IoT Greengrass Core software
psexec -s cmd /c cmdkey /generic:ggc_user /user:ggc_user /pass:password
If the PsExec License Agreement opens, choose Accept to agree to the license and run the
command.
Note
On Windows devices, the LocalSystem account runs the Greengrass nucleus, and you must
use the PsExec utility to store the default user information in the LocalSystem account.
Using the Credential Manager application stores this information in the Windows account of
the currently logged on user, instead of the LocalSystem account.
Step 3: Install the AWS IoT Greengrass Core
software
Follow the steps in this section to set up your Raspberry Pi as a AWS IoT Greengrass core device that you
can use for local development. In this section, you download and run an installer that does the following
to configure the AWS IoT Greengrass Core software for your device:
• Installs the Greengrass nucleus component. The nucleus is a mandatory component and is the
minimum requirement to run the AWS IoT Greengrass Core software on a device. For more
information, see Greengrass nucleus component (p. 181).
• Registers your device as an AWS IoT thing and downloads a digital certificate that allows your device
to connect to AWS. For more information, see Device authentication and authorization for AWS IoT
Greengrass (p. 773).
• Adds the device's AWS IoT thing to a thing group, which is a group or fleet of AWS IoT things.
Thing groups enable you to manage fleets of Greengrass core devices. When you deploy software
components to your devices, you can choose to deploy to individual devices or to groups of devices.
For more information, see Managing devices with AWS IoT in the AWS IoT Core Developer Guide.
• Creates the IAM role that allows your Greengrass core device to interact with AWS services. By default,
this role allows your device to interact with AWS IoT and send logs to Amazon CloudWatch Logs. For
more information, see Authorize core devices to interact with AWS services (p. 790).
• Installs the AWS IoT Greengrass command line interface (greengrass-cli), which you can use to
test custom components that you develop on the core device. For more information, see Greengrass
Command Line Interface (p. 428).
Install the AWS IoT Greengrass Core software (console)
1. Sign in to the AWS IoT Greengrass console.
2. Under Get started with Greengrass, choose Set up one core device.
3. Under Step 1: Register a Greengrass core device, for Core device name, enter the name of the AWS
IoT thing for your Greengrass core device. If the thing doesn't exist, the installer creates it.
4. Under Step 2: Add to a thing group to apply a continuous deployment, for Thing group, choose
the AWS IoT thing group to which you want to add your core device.
• If you select Enter a new group name, then in Thing group name, enter the name of the new
group to create. The installer creates the new group for you.
• If you select Select an existing group, then in Thing group name, choose the existing group that
you want to use.
• If you select No group, then the installer doesn't add the core device to a thing group.
5. Under Step 3: Install the Greengrass Core software, complete the following steps.
35
AWS IoT Greengrass Developer Guide, Version 2
Step 3: Install the AWS IoT Greengrass Core software
a. Choose your core device's operating system: Linux or Windows.
b. Provide your AWS credentials to the device so that the installer can provision the AWS IoT and
IAM resources for your core device. To increase security, you can get credentials for an IAM role
that allows only the minimum permissions necessary to provision. For more information, see
Minimal IAM policy for installer to provision resources (p. 793).
Note
The installer doesn't save or store your credentials.
On your device, do one of the following to retrieve credentials and make them available to the
AWS IoT Greengrass Core software installer:
• Use long-term credentials from an IAM user:
i. Provide the access key ID and secret access key for your IAM user. For more information
about how to retrieve long-term credentials, see Managing access keys for IAM users in
the IAM User Guide.
ii. Run the following commands to provide the credentials to the AWS IoT Greengrass
Core software.
Linux or Unix
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Windows Command Prompt (CMD)
set AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
set AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
PowerShell
$env:AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
$env:AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
• (Recommended) Use temporary security credentials from an IAM role:
i. Provide the access key ID, secret access key, and session token from an IAM role that
you assume. For more information about how to retrieve these credentials, see Using
temporary security credentials with the AWS CLI in the IAM User Guide.
ii. Run the following commands to provide the credentials to the AWS IoT Greengrass
Core software.
Linux or Unix
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_SESSION_TOKEN=AQoDYXdzEJr1K...o5OytwEXAMPLE=
Windows Command Prompt (CMD)
set AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
set AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
set AWS_SESSION_TOKEN=AQoDYXdzEJr1K...o5OytwEXAMPLE=
36
AWS IoT Greengrass Developer Guide, Version 2
Step 3: Install the AWS IoT Greengrass Core software
PowerShell
$env:AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
$env:AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
$env:AWS_SESSION_TOKEN="AQoDYXdzEJr1K...o5OytwEXAMPLE="
c. Under Run the installer, complete the following steps.
i. Under Download the installer, choose Copy and run the copied command on your core
device. This command downloads the latest version of the AWS IoT Greengrass Core
software and unzips it on your device.
ii. Under Run the installer, choose Copy, and run the copied command on your core device.
This command uses the AWS IoT thing and thing group names that you specified earlier to
run the AWS IoT Greengrass Core software installer and set up AWS resources for your core
device.
This command also does the following:
• Set up the AWS IoT Greengrass Core software as a system service that runs as boot. On
Linux devices, this requires the Systemd init system.
• Deploy the AWS IoT Greengrass CLI component (p. 428), which is a command-line tool
that enables you to develop custom Greengrass components on the core device.
• Specify to use the ggc_user system user to run software components on the core
device. On Linux devices, this command also specifies to use the ggc_group system
group, and the installer creates the system user and group for you.
When you run this command, you should see the following messages to indicate that the
installer succeeded.
Successfully configured Nucleus with provisioned resource details!
Configured Nucleus to deploy aws.greengrass.Cli component
Successfully set up Nucleus as a system service
Note
If you have a Linux device and it doesn't have systemd, the installer won't set
up the software as a system service, and you won't see the success message for
setting up the nucleus as a system service.
Install the AWS IoT Greengrass Core software (CLI)
To install and configure the AWS IoT Greengrass Core software
1. On your Greengrass core device, run the following command to switch to the home directory.
Linux or Unix
cd ~
Windows Command Prompt (CMD)
cd %USERPROFILE%
37
AWS IoT Greengrass Developer Guide, Version 2
Step 3: Install the AWS IoT Greengrass Core software
PowerShell
cd ~
2. On your core device, download the AWS IoT Greengrass Core software to a file named
greengrass-nucleus-latest.zip.
Linux or Unix
curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-
latest.zip > greengrass-nucleus-latest.zip
Windows Command Prompt (CMD)
curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-
latest.zip > greengrass-nucleus-latest.zip
PowerShell
iwr -Uri https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-
latest.zip -OutFile greengrass-nucleus-latest.zip
By downloading this software, you agree to the Greengrass Core Software License Agreement.
3. Unzip the AWS IoT Greengrass Core software to a folder on your device. Replace
GreengrassInstaller with the folder that you want to use.
Linux or Unix
unzip greengrass-nucleus-latest.zip -d GreengrassInstaller && rm greengrass-
nucleus-latest.zip
Windows Command Prompt (CMD)
mkdir GreengrassInstaller && tar -xf greengrass-nucleus-latest.zip -
C GreengrassInstaller && del greengrass-nucleus-latest.zip
PowerShell
Expand-Archive -Path greengrass-nucleus-latest.zip -DestinationPath .
\GreengrassInstaller
rm greengrass-nucleus-latest.zip
4. Run the following command to launch the AWS IoT Greengrass Core software installer. This
command does the following:
• Create the AWS resources that the core device requires to operate.
• Set up the AWS IoT Greengrass Core software as a system service that runs as boot. On Linux
devices, this requires the Systemd init system.
• Deploy the AWS IoT Greengrass CLI component (p. 428), which is a command-line tool that
enables you to develop custom Greengrass components on the core device.
• Specify to use the ggc_user system user to run software components on the core device. On
Linux devices, this command also specifies to use the ggc_group system group, and the installer
creates the system user and group for you.
38
AWS IoT Greengrass Developer Guide, Version 2
Step 3: Install the AWS IoT Greengrass Core software
Replace argument values in your command as follows.
a. /greengrass/v2 or C:\greengrass\v2: The path to the root folder to use to install the AWS
IoT Greengrass Core software.
b. GreengrassInstaller. The path to the folder where you unpacked the AWS IoT Greengrass
Core software installer.
c. region. The AWS Region in which to find or create resources.
d. MyGreengrassCore. The name of the AWS IoT thing for your Greengrass core device. If
the thing doesn't exist, the installer creates it. The installer downloads the certificates to
authenticate as the AWS IoT thing. For more information, see Device authentication and
authorization for AWS IoT Greengrass (p. 773).
Note
The thing name can't contain colon (:) characters.
e. MyGreengrassCoreGroup. The name of AWS IoT thing group for your Greengrass core device.
If the thing group doesn't exist, the installer creates it and adds the thing to it. If the thing
group exists and has an active deployment, the core device downloads and runs the software
that the deployment specifies.
Note
The thing group name can't contain colon (:) characters.
f. GreengrassV2IoTThingPolicy. The name of the AWS IoT policy that allows the Greengrass
core devices to communicate with AWS IoT and AWS IoT Greengrass. If the AWS IoT policy
doesn't exist, the installer creates a permissive AWS IoT policy with this name. You can restrict
this policy's permissions for you use case. For more information, see Minimal AWS IoT policy for
AWS IoT Greengrass V2 core devices (p. 777).
g. GreengrassV2TokenExchangeRole. The name of the IAM role that allows the Greengrass
core device to get temporary AWS credentials. If the role doesn't exist, the installer creates it
and creates and attaches a policy named GreengrassV2TokenExchangeRoleAccess. For
more information, see Authorize core devices to interact with AWS services (p. 790).
h. GreengrassCoreTokenExchangeRoleAlias. The alias to the IAM role that allows the
Greengrass core device to get temporary credentials later. If the role alias doesn't exist, the
installer creates it and points it to the IAM role that you specify. For more information, see
Authorize core devices to interact with AWS services (p. 790).
Linux or Unix
sudo -E java -Droot="/greengrass/v2" -Dlog.store=FILE \
-jar ./GreengrassInstaller/lib/Greengrass.jar \
--aws-region region \
--thing-name MyGreengrassCore \
--thing-group-name MyGreengrassCoreGroup \
--thing-policy-name GreengrassV2IoTThingPolicy \
--tes-role-name GreengrassV2TokenExchangeRole \
--tes-role-alias-name GreengrassCoreTokenExchangeRoleAlias \
--component-default-user ggc_user:ggc_group \
--provision true \
--setup-system-service true \
--deploy-dev-tools true
Windows Command Prompt (CMD)
java -Droot="C:\greengrass\v2" "-Dlog.store=FILE" ^
-jar ./GreengrassInstaller/lib/Greengrass.jar ^
--aws-region region ^
39
AWS IoT Greengrass Developer Guide, Version 2
(Optional) Run the Greengrass software (Linux)
--thing-name MyGreengrassCore ^
--thing-group-name MyGreengrassCoreGroup ^
--thing-policy-name GreengrassV2IoTThingPolicy ^
--tes-role-name GreengrassV2TokenExchangeRole ^
--tes-role-alias-name GreengrassCoreTokenExchangeRoleAlias ^
--component-default-user ggc_user ^
--provision true ^
--setup-system-service true ^
--deploy-dev-tools true
PowerShell
java -Droot="C:\greengrass\v2" "-Dlog.store=FILE" `
-jar ./GreengrassInstaller/lib/Greengrass.jar `
--aws-region region `
--thing-name MyGreengrassCore `
--thing-group-name MyGreengrassCoreGroup `
--thing-policy-name GreengrassV2IoTThingPolicy `
--tes-role-name GreengrassV2TokenExchangeRole `
--tes-role-alias-name GreengrassCoreTokenExchangeRoleAlias `
--component-default-user ggc_user `
--provision true `
--setup-system-service true `
--deploy-dev-tools true
Note
If you are running AWS IoT Greengrass on a device with limited memory, you can control
the amount of memory that AWS IoT Greengrass Core software uses. To control memory
allocation, you can set JVM heap size options in the jvmOptions configuration parameter
in your nucleus component. For more information, see Control memory allocation with JVM
options (p. 160).
When you run this command, you should see the following messages to indicate that the installer
succeeded.
Successfully configured Nucleus with provisioned resource details!
Configured Nucleus to deploy aws.greengrass.Cli component
Successfully set up Nucleus as a system service
Note
If you have a Linux device and it doesn't have systemd, the installer won't set up the
software as a system service, and you won't see the success message for setting up the
nucleus as a system service.
(Optional) Run the Greengrass software (Linux)
If you installed the software as a system service, the installer runs the software for you. Otherwise,
you must run the software. To see if the installer set up the software as a system service, look for the
following line in the installer output.
Successfully set up Nucleus as a system service
If you don't see this message, do the following to run the software:
1. Run the following command to run the software.
40
AWS IoT Greengrass Developer Guide, Version 2
Verify the Greengrass CLI installation on the device
sudo /greengrass/v2/alts/current/distro/bin/loader
The software prints the following message if it launches successfully.
Launched Nucleus successfully.
2. You must leave the current command shell open to keep the AWS IoT Greengrass Core software
running. If you use SSH to connect to the core device, run the following command on your
development computer to open a second SSH session that you can use to run additional commands
on the core device. Replace username with the name of the user to sign in, and replace pi-ip-
address with the IP address of the device.
ssh username@pi-ip-address
For more information about how to interact with the Greengrass system service, see Configure the
Greengrass nucleus as a system service (p. 158).
Verify the Greengrass CLI installation on the device
The Greengrass CLI can take up to a minute to deploy. Run the following command to check the status of
the deployment. Replace MyGreengrassCore with the name of your core device.
aws greengrassv2 list-effective-deployments --core-device-thing-name MyGreengrassCore
The coreDeviceExecutionStatus indicates the status of the deployment to the core device. When
the status is SUCCEEDED, run the following command to verify that the Greengrass CLI is installed and
runs. Replace /greengrass/v2 with the path to the root folder.
Linux or Unix
/greengrass/v2/bin/greengrass-cli help
Windows Command Prompt (CMD)
C:\greengrass\v2\bin\greengrass-cli help
PowerShell
C:\greengrass\v2\bin\greengrass-cli help
The command outputs help information for the Greengrass CLI. If the greengrass-cli isn't found, the
deployment might have failed to install the Greengrass CLI. For more information, see Troubleshooting
AWS IoT Greengrass V2 (p. 911).
You can also run the following command to manually deploy the AWS IoT Greengrass CLI to your device.
• Replace region with the AWS Region that you use. Make sure that you use the same AWS Region that
you used to configure the AWS CLI on your device.
• Replace account-id with your AWS account ID.
• Replace MyGreengrassCore with the name of your core device.
41
AWS IoT Greengrass Developer Guide, Version 2
Step 4: Develop and test a component on your device
Linux, macOS, or Unix
aws greengrassv2 create-deployment \
--target-arn "arn:aws:iot:region:account-id:thing/MyGreengrassCore" \
--components '{
"aws.greengrass.Cli": {
"componentVersion": "2.5.2"
}
}'
Windows Command Prompt (CMD)
aws greengrassv2 create-deployment ^
--target-arn "arn:aws:iot:region:account-id:thing/MyGreengrassCore" ^
--components "{\"aws.greengrass.Cli\":{\"componentVersion\":\"2.5.2\"}}"
PowerShell
aws greengrassv2 create-deployment `
--target-arn "arn:aws:iot:region:account-id:thing/MyGreengrassCore" `
--components '{\"aws.greengrass.Cli\":{\"componentVersion\":\"2.5.2\"}}'
Tip
You can add /greengrass/v2/bin (Linux) or C:\greengrass\v2\bin (Windows) to your
PATH environment variable to run greengrass-cli without its absolute path.
The AWS IoT Greengrass Core software and local development tools run on your device. Next, you can
develop a Hello World AWS IoT Greengrass component on your device.
Step 4: Develop and test a component on your
device
A component is a software module that runs on AWS IoT Greengrass core devices. Components enable
you to create and manage complex applications as discrete building blocks that you can reuse from one
Greengrass core device to another. Every component is composed of a recipe and artifacts.
• Recipes
Every component contains a recipe file, which defines its metadata. The recipe also specifies
the component's configuration parameters, component dependencies, lifecycle, and platform
compatibility. The component lifecycle defines the commands that install, run, and shut down the
component. For more information, see AWS IoT Greengrass component recipe reference (p. 471).
You can define recipes in JSON or YAML format.
• Artifacts
Components can have any number of artifacts, which are component binaries. Artifacts can include
scripts, compiled code, static resources, and any other files that a component consumes. Components
can also consume artifacts from component dependencies.
With AWS IoT Greengrass, you can use the Greengrass CLI to develop and test components locally
on a Greengrass core device without interaction with the AWS Cloud. When you complete your local
42
AWS IoT Greengrass Developer Guide, Version 2
Step 4: Develop and test a component on your device
component, you can use the component recipe and artifacts to create that component in the AWS IoT
Greengrass service in the AWS Cloud, and then deploy it to all of your Greengrass core devices. For more
information about components, see Develop AWS IoT Greengrass components (p. 440).
In this section, you learn how to create and run a basic Hello World component locally on your core
device.
To develop a Hello World component on your device
1. Create a folder for your components with subfolders for recipes and artifacts. Run the following
commands on your Greengrass core device to create these folders and change to the component
folder. Replace ~/greengrassv2 or %USERPROFILE%\greengrassv2 with the path to the folder
to use for local development.
Linux or Unix
mkdir -p ~/greengrassv2/{recipes,artifacts}
cd ~/greengrassv2
Windows Command Prompt (CMD)
mkdir %USERPROFILE%\greengrassv2\recipes, %USERPROFILE%\greengrassv2\artifacts
cd %USERPROFILE%\greengrassv2
PowerShell
mkdir ~/greengrassv2/recipes, ~/greengrassv2/artifacts
cd ~/greengrassv2
2. Use a text editor to create a recipe file that defines your component's metadata, parameters,
dependencies, lifecycle, and platform capability. Include the component version in the recipe file
name so that you can identify which recipe reflects which component version. You can choose YAML
or JSON format for your recipe.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
JSON
nano recipes/com.example.HelloWorld-1.0.0.json
YAML
nano recipes/com.example.HelloWorld-1.0.0.yaml
Note
AWS IoT Greengrass uses semantic versions for components. Semantic versions follow a
major.minor.patch number system. For example, version 1.0.0 represents the first major
release for a component. For more information, see the semantic version specification.
3. Paste the following recipe into the file.
JSON
{
"RecipeFormatVersion": "2020-01-25",
43
AWS IoT Greengrass Developer Guide, Version 2
Step 4: Develop and test a component on your device
"ComponentName": "com.example.HelloWorld",
"ComponentVersion": "1.0.0",
"ComponentDescription": "My first AWS IoT Greengrass component.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"Message": "world"
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"Run": "python3 -u {artifacts:path}/hello_world.py \"{configuration:/
Message}\""
}
},
{
"Platform": {
"os": "windows"
},
"Lifecycle": {
"Run": "py -3 -u {artifacts:path}/hello_world.py \"{configuration:/
Message}\""
}
}
]
}
YAML
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.HelloWorld
ComponentVersion: '1.0.0'
ComponentDescription: My first AWS IoT Greengrass component.
ComponentPublisher: Amazon
ComponentConfiguration:
DefaultConfiguration:
Message: world
Manifests:
- Platform:
os: linux
Lifecycle:
Run: |
python3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
- Platform:
os: windows
Lifecycle:
Run: |
py -3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
This recipe's ComponentConfiguration section defines a parameter, Message, that defaults
to world. The Manifests section defines a manifest, which is a set of lifecycle instructions and
artifacts for a platform. You can define multiple manifests to specify different install instructions
for various platforms, for example. In the manifest, the Lifecycle section instructs the Greengrass
core device to run the Hello World script with the Message parameter value as an argument.
4. Run the following command to create a folder for the component artifacts.
44
AWS IoT Greengrass Developer Guide, Version 2
Step 4: Develop and test a component on your device
Linux or Unix
mkdir -p artifacts/com.example.HelloWorld/1.0.0
Windows Command Prompt (CMD)
mkdir artifacts\com.example.HelloWorld\1.0.0
PowerShell
mkdir artifacts\com.example.HelloWorld\1.0.0
Important
You must use the following format for the artifact folder path. Include the component
name and version that you specify in the recipe.
artifacts/componentName/componentVersion/
5. Use a text editor to create a Python script artifact file for your Hello World component.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano artifacts/com.example.HelloWorld/1.0.0/hello_world.py
Copy and paste the following Python script into the file.
import sys
message = "Hello, %s!" % sys.argv[1]
# Print the message to stdout, which Greengrass saves in a log file.
print(message)
6. Use the local AWS IoT Greengrass CLI to manage components on your Greengrass core device.
Run the following command to deploy the component to the AWS IoT Greengrass core. Replace /
greengrass/v2 or C:\greengrass\v2 with your AWS IoT Greengrass V2 root folder, and replace
~/greengrassv2 or %USERPROFILE%\greengrassv2 with your component development folder.
Linux or Unix
sudo /greengrass/v2/bin/greengrass-cli deployment create \
--recipeDir ~/greengrassv2/recipes \
--artifactDir ~/greengrassv2/artifacts \
--merge "com.example.HelloWorld=1.0.0"
Windows Command Prompt (CMD)
C:\greengrass\v2\bin\greengrass-cli deployment create ^
--recipeDir %USERPROFILE%\greengrassv2\recipes ^
--artifactDir %USERPROFILE%\greengrassv2\artifacts ^
--merge "com.example.HelloWorld=1.0.0"
45
AWS IoT Greengrass Developer Guide, Version 2
Step 4: Develop and test a component on your device
PowerShell
C:\greengrass\v2\bin\greengrass-cli deployment create `
--recipeDir ~/greengrassv2/recipes `
--artifactDir ~/greengrassv2/artifacts `
--merge "com.example.HelloWorld=1.0.0"
This command adds the component that uses the recipe in recipes and the Python script in
artifacts. The --merge option adds or updates the component and version that you specify.
7. The AWS IoT Greengrass Core software saves stdout from component process to log files in the
logs folder. Run the following command to verify that the Hello World component runs and prints
messages.
Linux or Unix
sudo tail -f /greengrass/v2/logs/com.example.HelloWorld.log
Windows Command Prompt (CMD)
type C:\greengrass\v2\logs\com.example.HelloWorld.log
The type command writes the file's contents to the terminal. Run this command multiple times
to observe changes in the file.
PowerShell
gc C:\greengrass\v2\logs\com.example.HelloWorld.log -Tail 10 -Wait
You should see messages similar to the following example.
Hello, world!
Note
If the file doesn't exist, the local deployment may not be complete yet. If the file doesn't
exist within 15 seconds, the deployment likely failed. This can occur if your recipe isn't valid,
for example. Run the following command to view the AWS IoT Greengrass core log file. This
file includes logs from the Greengrass core device's deployment service.
Linux or Unix
sudo tail -f /greengrass/v2/logs/greengrass.log
Windows Command Prompt (CMD)
type C:\greengrass\v2\logs\greengrass.log
The type command writes the file's contents to the terminal. Run this command
multiple times to observe changes in the file.
PowerShell
gc C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
46
AWS IoT Greengrass Developer Guide, Version 2
Step 4: Develop and test a component on your device
8. Modify the local component to iterate and test your code. Open hello_world.py in a text editor,
and add the following code at line 4 to edit the message that the AWS IoT Greengrass core logs.
message += " Greetings from your first Greengrass component."
The hello_world.py script should now have the following contents.
import sys
message = "Hello, %s!" % sys.argv[1]
message += " Greetings from your first Greengrass component."
# Print the message to stdout, which Greengrass saves in a log file.
print(message)
9. Run the following command to update the component with your changes.
Linux or Unix
sudo /greengrass/v2/bin/greengrass-cli deployment create \
--recipeDir ~/greengrassv2/recipes \
--artifactDir ~/greengrassv2/artifacts \
--merge "com.example.HelloWorld=1.0.0"
Windows Command Prompt (CMD)
C:\greengrass\v2\bin\greengrass-cli deployment create ^
--recipeDir %USERPROFILE%\greengrassv2\recipes ^
--artifactDir %USERPROFILE%\greengrassv2\artifacts ^
--merge "com.example.HelloWorld=1.0.0"
PowerShell
C:\greengrass\v2\bin\greengrass-cli deployment create `
--recipeDir ~/greengrassv2/recipes `
--artifactDir ~/greengrassv2/artifacts `
--merge "com.example.HelloWorld=1.0.0"
This command updates the com.example.HelloWorld component with the latest Hello World
artifact.
10. Run the following command to restart the component. When you restart a component, the core
device uses the latest changes.
Linux or Unix
sudo /greengrass/v2/bin/greengrass-cli component restart \
--names "com.example.HelloWorld"
Windows Command Prompt (CMD)
C:\greengrass\v2\bin\greengrass-cli component restart ^
--names "com.example.HelloWorld"
47
AWS IoT Greengrass Developer Guide, Version 2
Step 4: Develop and test a component on your device
PowerShell
C:\greengrass\v2\bin\greengrass-cli component restart `
--names "com.example.HelloWorld"
11. Check the log again to verify that the Hello World component prints the new message.
Linux or Unix
sudo tail -f /greengrass/v2/logs/com.example.HelloWorld.log
Windows Command Prompt (CMD)
type C:\greengrass\v2\logs\com.example.HelloWorld.log
The type command writes the file's contents to the terminal. Run this command multiple times
to observe changes in the file.
PowerShell
gc C:\greengrass\v2\logs\com.example.HelloWorld.log -Tail 10 -Wait
You should see messages similar to the following example.
Hello, world! Greetings from your first Greengrass component.
12. You can update the component's configuration parameters to test different configurations. When
you deploy a component, you can specify a configuration update, which defines how to modify
the component's configuration on the core device. You can specify which configuration values to
reset to default values and the new configuration values to merge onto the core device. For more
information, see Update component configurations (p. 500).
Do the following:
a. Use a text editor to create a file called hello-world-config-update.json to contain the
configuration update
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano hello-world-config-update.json
b. Copy and paste the following JSON object into the file. This JSON object defines a configuration
update that merges the value friend to the Message parameter to update its value. This
configuration update doesn't specify any values to reset. You don't need to reset the Message
parameter because the merge update replaces the existing value.
{
"com.example.HelloWorld": {
"MERGE": {
"Message": "friend"
}
}
}
c. Run the following command to deploy the configuration update to the Hello World component.
48
AWS IoT Greengrass Developer Guide, Version 2
Step 4: Develop and test a component on your device
Linux or Unix
sudo /greengrass/v2/bin/greengrass-cli deployment create \
--merge "com.example.HelloWorld=1.0.0" \
--update-config hello-world-config-update.json
Windows Command Prompt (CMD)
C:\greengrass\v2\bin\greengrass-cli deployment create ^
--merge "com.example.HelloWorld=1.0.0" ^
--update-config hello-world-config-update.json
PowerShell
C:\greengrass\v2\bin\greengrass-cli deployment create `
--merge "com.example.HelloWorld=1.0.0" `
--update-config hello-world-config-update.json
d. Check the log again to verify that the Hello World component outputs the new message.
Linux or Unix
sudo tail -f /greengrass/v2/logs/com.example.HelloWorld.log
Windows Command Prompt (CMD)
type C:\greengrass\v2\logs\com.example.HelloWorld.log
The type command writes the file's contents to the terminal. Run this command multiple
times to observe changes in the file.
PowerShell
gc C:\greengrass\v2\logs\com.example.HelloWorld.log -Tail 10 -Wait
You should see messages similar to the following example.
Hello, friend! Greetings from your first Greengrass component.
13. After you finish testing your component, remove it from your core device. Run the following
command.
Linux or Unix
sudo /greengrass/v2/bin/greengrass-cli deployment create --
remove="com.example.HelloWorld"
Windows Command Prompt (CMD)
C:\greengrass\v2\bin\greengrass-cli deployment create --
remove="com.example.HelloWorld"
49
AWS IoT Greengrass Developer Guide, Version 2
Step 5: Create your component in
the AWS IoT Greengrass service
PowerShell
C:\greengrass\v2\bin\greengrass-cli deployment create --
remove="com.example.HelloWorld"
Important
This step is required for you to deploy the component back to the core device after
you upload it to AWS IoT Greengrass. Otherwise, the deployment fails with a version
compatibility error because the local deployment specifies a different version of the
component.
Run the following command and verify that the com.example.HelloWorld component doesn't
appear in the list of components on your device.
Linux or Unix
sudo /greengrass/v2/bin/greengrass-cli component list
Windows Command Prompt (CMD)
C:\greengrass\v2\bin\greengrass-cli component list
PowerShell
C:\greengrass\v2\bin\greengrass-cli component list
Your Hello World component is complete, and you can now upload it to the AWS IoT Greengrass cloud
service. Then, you can deploy the component to Greengrass core devices.
Step 5: Create your component in the AWS IoT
Greengrass service
When you finish developing a component on your core device, you can upload it to the AWS IoT
Greengrass service in the AWS Cloud. You can also directly create the component in the AWS IoT
Greengrass console. AWS IoT Greengrass provides a component management service that hosts
your components so that you can deploy them to individual devices or fleets of devices. To upload a
component to the AWS IoT Greengrass service, you complete the following steps:
• Upload component artifacts to an S3 bucket.
• Add each artifact's Amazon Simple Storage Service (Amazon S3) URI to the component recipe.
• Create a component in AWS IoT Greengrass from the component recipe.
In this section, you complete these steps on your Greengrass core device to upload your Hello World
component to the AWS IoT Greengrass service.
50
AWS IoT Greengrass Developer Guide, Version 2
Step 5: Create your component in
the AWS IoT Greengrass service
Create your component in AWS IoT Greengrass (console)
1. Use an S3 bucket in your AWS account to host AWS IoT Greengrass component artifacts. When you
deploy the component to a core device, the device downloads the component's artifacts from the
bucket.
You can use an existing S3 bucket, or you can create a new bucket.
a. In the Amazon S3 console, under Buckets, choose Create bucket.
b. For Bucket name, enter a unique bucket name. For example, you can use greengrass-
component-artifacts-123456789012-region. Replace 123456789012 with your AWS
account ID and region with the AWS Region that you use for this tutorial.
c. For AWS region, select the AWS Region that you use for this tutorial.
d. Choose Create bucket.
e. Under Buckets, choose the bucket that you created, upload the hello_world.py script to the
artifacts/com.example.HelloWorld/1.0.0 folder in the bucket. For information about
uploading objects to S3 buckets, see Uploading objects in the Amazon Simple Storage Service
User Guide.
f. Copy the S3 URI of the hello_world.py object in the S3 bucket. This URI should look similar
to the following example. Replace DOC-EXAMPLE-BUCKET with the name of the S3 bucket.
s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py
2. Allow the core device to access component artifacts in the S3 bucket.
Each core device has a core device IAM role (p. 790) that allows it to interact with AWS IoT and
send logs to the AWS Cloud. This device role doesn't allow access to S3 buckets by default, so you
must create and attach a policy that allows the core device to retrieve component artifacts from the
S3 bucket.
If your device's role already allows access to the S3 bucket, you can skip this step. Otherwise, create
an IAM policy that allows access and attach it to the role, as follows:
a. In the IAM console navigation menu, choose Policies, and then choose Create policy.
b. On the JSON tab, replace the placeholder content with the following policy. Replace DOC-
EXAMPLE-BUCKET with the name of the bucket to use.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject"
],
"Resource": "arn:aws:s3:::DOC-EXAMPLE-BUCKET/*"
}
]
}
c. Choose Next: Tags, and then choose Next: Review.
d. For Name, enter MyGreengrassV2ComponentArtifactPolicy.
e. Choose Create policy.
f. In the IAM console navigation menu, choose Role, and then choose the
GreengrassV2TokenExchangeRole role that you specified when you ran the AWS IoT
Greengrass Core software.
51
AWS IoT Greengrass Developer Guide, Version 2
Step 5: Create your component in
the AWS IoT Greengrass service
g. Under Permissions, choose Attach policies.
h. On the Attach Permissions page, select the check box next to the
MyGreengrassV2ComponentArtifactPolicy policy that you created, and then choose
Attach policy.
3. Use the component recipe to create a component in the AWS IoT Greengrass console.
a. In the AWS IoT Greengrass console navigation menu, choose Components, and then choose
Create component.
b. Under Component information, choose Enter recipe as JSON. The placeholder recipe should
look similar to the following example.
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.HelloWorld",
"ComponentVersion": "1.0.0",
"ComponentDescription": "My first Greengrass component.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"Message": "world"
}
},
"Manifests": [
{
"Lifecycle": {
"Run": "python3 -u {artifacts:path}/hello_world.py \"{configuration:/
Message}\""
},
"Artifacts": [
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/
hello_world.py"
}
]
}
]
}
c. Replace the placeholder URI with S3 URI of your hello_world.py object.
d. Choose Create component.
e. On the com.example.HelloWorld component page, verify that the Status of the component is
Deployable.
Create your component in AWS IoT Greengrass (AWS CLI)
To upload your Hello World component
1. Use an S3 bucket in your AWS account to host AWS IoT Greengrass component artifacts. When you
deploy the component to a core device, the device downloads the component's artifacts from the
bucket.
You can use an existing S3 bucket, or run the following command to create a bucket. This command
creates a bucket with your AWS account ID and AWS Region to form a unique bucket name. Replace
123456789012 with your AWS account ID and region with the AWS Region that you use for this
tutorial.
aws s3 mb s3://greengrass-component-artifacts-123456789012-region
52
AWS IoT Greengrass Developer Guide, Version 2
Step 5: Create your component in
the AWS IoT Greengrass service
The command outputs the following information if the request succeeds.
make_bucket: greengrass-component-artifacts-123456789012-region
2. Allow the core device to access component artifacts in the S3 bucket.
Each core device has a core device IAM role (p. 790) that allows it to interact with AWS IoT and
send logs to the AWS Cloud. This device role doesn't allow access to S3 buckets by default, so you
must create and attach a policy that allows the core device to retrieve component artifacts from the
S3 bucket.
If your device's role already allows access to the S3 bucket, you can skip this step. Otherwise, create
an IAM policy that allows access and attach it to the role, as follows:
a. Create a file called component-artifact-policy.json and copy the following JSON into
the file. This policy allows access to all files in the S3 bucket that you created in the previous
step. Replace DOC-EXAMPLE-BUCKET with the name of the bucket to use.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject"
],
"Resource": "arn:aws:s3:::DOC-EXAMPLE-BUCKET/*"
}
]
}
b. Run the following command to create the policy from the policy document in component-
artifact-policy.json.
Linux or Unix
aws iam create-policy \
--policy-name MyGreengrassV2ComponentArtifactPolicy \
--policy-document file://component-artifact-policy.json
Windows Command Prompt (CMD)
aws iam create-policy ^
--policy-name MyGreengrassV2ComponentArtifactPolicy ^
--policy-document file://component-artifact-policy.json
PowerShell
aws iam create-policy `
--policy-name MyGreengrassV2ComponentArtifactPolicy `
--policy-document file://component-artifact-policy.json
Copy the policy Amazon Resource Name (ARN) from the policy metadata in the output. You use
this ARN to attach this policy to the core device role in the next step.
c. Run the following command to attach the policy to the core device role. Replace
GreengrassV2TokenExchangeRole with the name of the role that you specified when you
53
AWS IoT Greengrass Developer Guide, Version 2
Step 5: Create your component in
the AWS IoT Greengrass service
ran the AWS IoT Greengrass Core software. Replace the policy ARN with the ARN from the
previous step.
Linux or Unix
aws iam attach-role-policy \
--role-name GreengrassV2TokenExchangeRole \
--policy-arn
arn:aws:iam::123456789012:policy/MyGreengrassV2ComponentArtifactPolicy
Windows Command Prompt (CMD)
aws iam attach-role-policy ^
--role-name GreengrassV2TokenExchangeRole ^
--policy-arn
arn:aws:iam::123456789012:policy/MyGreengrassV2ComponentArtifactPolicy
PowerShell
aws iam attach-role-policy `
--role-name GreengrassV2TokenExchangeRole `
--policy-arn
arn:aws:iam::123456789012:policy/MyGreengrassV2ComponentArtifactPolicy
If the command has no output, it succeeded. Your core device can now access artifacts that you
upload to this S3 bucket.
3. Upload the Hello World Python script artifact to the S3 bucket.
Run the following command to upload the script to the same path in the bucket where the script
exists on your AWS IoT Greengrass core. Replace DOC-EXAMPLE-BUCKET with the name of the S3
bucket.
Linux or Unix
aws s3 cp \
artifacts/com.example.HelloWorld/1.0.0/hello_world.py \
s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py
Windows Command Prompt (CMD)
aws s3 cp ^
artifacts/com.example.HelloWorld/1.0.0/hello_world.py ^
s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py
PowerShell
aws s3 cp `
artifacts/com.example.HelloWorld/1.0.0/hello_world.py `
s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py
The command outputs a line that starts with upload: if the request succeeds.
4. Add the artifact's Amazon S3 URI to the component recipe.
54
AWS IoT Greengrass Developer Guide, Version 2
Step 5: Create your component in
the AWS IoT Greengrass service
The Amazon S3 URI is composed of the bucket name and the path to the artifact object in the
bucket. Your script artifact's Amazon S3 URI is the URI that you upload the artifact to in the previous
step. This URI should look similar to the following example. Replace DOC-EXAMPLE-BUCKET with
the name of the S3 bucket.
s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py
To add the artifact to the recipe, add a list of Artifacts that contains a structure with the Amazon
S3 URI.
JSON
"Artifacts": [
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/
hello_world.py"
}
]
Open the recipe file in a text editor.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano recipes/com.example.HelloWorld-1.0.0.json
Add the artifact to the recipe. Your recipe file should look similar to the following example.
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.HelloWorld",
"ComponentVersion": "1.0.0",
"ComponentDescription": "My first Greengrass component.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"Message": "world"
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"Run": "python3 -u {artifacts:path}/hello_world.py \"{configuration:/
Message}\""
},
"Artifacts": [
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/
hello_world.py"
}
]
},
{
"Platform": {
"os": "windows"
},
55
AWS IoT Greengrass Developer Guide, Version 2
Step 5: Create your component in
the AWS IoT Greengrass service
"Lifecycle": {
"Run": "py -3 -u {artifacts:path}/hello_world.py \"{configuration:/
Message}\""
},
"Artifacts": [
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/
hello_world.py"
}
]
}
]
}
YAML
Artifacts:
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/
hello_world.py
Open the recipe file in a text editor.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano recipes/com.example.HelloWorld-1.0.0.yaml
Add the artifact to the recipe. Your recipe file should look similar to the following example.
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.HelloWorld
ComponentVersion: '1.0.0'
ComponentDescription: My first AWS IoT Greengrass component.
ComponentPublisher: Amazon
ComponentConfiguration:
DefaultConfiguration:
Message: world
Manifests:
- Platform:
os: linux
Lifecycle:
Run: |
python3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
Artifacts:
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/
hello_world.py
- Platform:
os: windows
Lifecycle:
Run: |
py -3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
Artifacts:
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/
hello_world.py
5. Create a component resource in AWS IoT Greengrass from the recipe. Run the following command to
create the component from the recipe, which you provide as a binary file.
56
AWS IoT Greengrass Developer Guide, Version 2
Step 5: Create your component in
the AWS IoT Greengrass service
JSON
aws greengrassv2 create-component-version --inline-recipe fileb://recipes/
com.example.HelloWorld-1.0.0.json
YAML
aws greengrassv2 create-component-version --inline-recipe fileb://recipes/
com.example.HelloWorld-1.0.0.yaml
The response looks similar to the following example if the request succeeds.
{
"arn":
"arn:aws:greengrass:region:123456789012:components:com.example.HelloWorld:versions:1.0.0",
"componentName": "com.example.HelloWorld",
"componentVersion": "1.0.0",
"creationTimestamp": "Mon Nov 30 09:04:05 UTC 2020",
"status": {
"componentState": "REQUESTED",
"message": "NONE",
"errors": {}
}
}
Copy the arn from the output to check the state of the component in the next step.
Note
You can also see your Hello World component in the AWS IoT Greengrass console on the
Components page.
6. Verify that the component creates and is ready to be deployed. When you create a component, its
state is REQUESTED. Then, AWS IoT Greengrass validates that the component is deployable. You
can run the following command to query the component status and verify that your component is
deployable. Replace the arn with the ARN from the previous step.
aws greengrassv2 describe-component --arn
"arn:aws:greengrass:region:123456789012:components:com.example.HelloWorld:versions:1.0.0"
If the component validates, the response indicates that the component state is DEPLOYABLE.
{
"arn":
"arn:aws:greengrass:region:123456789012:components:com.example.HelloWorld:versions:1.0.0",
"componentName": "com.example.HelloWorld",
"componentVersion": "1.0.0",
"creationTimestamp": "2020-11-30T18:04:05.823Z",
"publisher": "Amazon",
"description": "My first Greengrass component.",
"status": {
"componentState": "DEPLOYABLE",
"message": "NONE",
"errors": {}
},
"platforms": [
{
"os": "linux",
"architecture": "all"
57
AWS IoT Greengrass Developer Guide, Version 2
Step 6: Deploy your component
}
]
}
Your Hello World component is now available in AWS IoT Greengrass. You can deploy it back to this
Greengrass core device or to other core devices.
Step 6: Deploy your component
With AWS IoT Greengrass, you can deploy components to individual devices or groups of devices. When
you deploy a component, AWS IoT Greengrass installs and runs that component's software on each
target device. You specify which components to deploy and the configuration update to deploy for each
component. You can also control how the deployment rolls out to the devices that the deployment
targets. For more information, see Deploy AWS IoT Greengrass components to devices (p. 491).
In this section, you deploy your Hello World component back to your Greengrass core device.
Deploy your component (console)
1. In the AWS IoT Greengrass console navigation menu, choose Components.
2. On the Components page, on the My components tab, choose com.example.HelloWorld.
3. On the com.example.HelloWorld page, choose Deploy.
4. From Add to deployment, choose Create new deployment, then choose Next.
5. On the Specify target page, do the following:
a. In the Name box, enter Deployment for MyGreengrassCore.
b. For Deployment target, choose Core device, and the name of the AWS IoT thing for your core
device. The default value in this tutorial is MyGreengrassCore.
c. Choose Next.
6. On the Select components page, under My components, verify that the com.example.HelloWorld
component is selected, and choose Next.
7. On the Configure components page, choose com.example.HelloWorld, and do the following:
a. Choose Configure component.
b. Under Configuration update, in Configuration to merge, enter the following configuration.
{
"Message": "universe"
}
This configuration update sets the Hello World Message parameter to universe for the device
in this deployment.
c. Choose Confirm.
d. Choose Next.
8. On the Configure advanced settings page, keep the default configuration settings, and choose
Next.
9. On the Review page, choose Deploy
58
AWS IoT Greengrass Developer Guide, Version 2
Step 6: Deploy your component
Deploy your component (AWS CLI)
To deploy your Hello World component
1. On your development computer, create a file called hello-world-deployment.json and copy
the following JSON into the file. This file defines the components and configurations to deploy.
{
"components": {
"com.example.HelloWorld": {
"componentVersion": "1.0.0",
"configurationUpdate": {
"merge": "{\"Message\":\"universe\"}"
}
}
}
}
This configuration file specifies to deploy version 1.0.0 of the Hello World component that you
developed and published in the previous procedure. The configurationUpdate specifies to merge
the component configuration in a JSON-encoded string. This configuration update sets the Hello
World Message parameter to universe for the device in this deployment.
2. Run the following command to deploy the component to your Greengrass core device. You can
deploy to things, which are individual devices, or thing groups, which are groups of devices. Replace
MyGreengrassCore with the name of the AWS IoT thing for your core device.
Linux or Unix
aws greengrassv2 create-deployment \
--target-arn "arn:aws:iot:region:account-id:thing/MyGreengrassCore" \
--cli-input-json file://hello-world-deployment.json
Windows Command Prompt (CMD)
aws greengrassv2 create-deployment ^
--target-arn "arn:aws:iot:region:account-id:thing/MyGreengrassCore" ^
--cli-input-json file://hello-world-deployment.json
PowerShell
aws greengrassv2 create-deployment `
--target-arn "arn:aws:iot:region:account-id:thing/MyGreengrassCore" `
--cli-input-json file://hello-world-deployment.json
The command outputs a response similar to the following example.
{
"deploymentId": "deb69c37-314a-4369-a6a1-3dff9fce73a9",
"iotJobId": "b5d92151-6348-4941-8603-bdbfb3e02b75",
"iotJobArn": "arn:aws:iot:region:account-id:job/b5d92151-6348-4941-8603-bdbfb3e02b75"
}
3. Verify that the deployment completes successfully. The deployment can take several minutes to
complete. Check the Hello World log to verify the change. Run the following command on your
Greengrass core device.
59
AWS IoT Greengrass Developer Guide, Version 2
Next steps
Linux or Unix
sudo tail -f /greengrass/v2/logs/com.example.HelloWorld.log
Windows Command Prompt (CMD)
type C:\greengrass\v2\logs\com.example.HelloWorld.log
The type command writes the file's contents to the terminal. Run this command multiple times
to observe changes in the file.
PowerShell
gc C:\greengrass\v2\logs\com.example.HelloWorld.log -Tail 10 -Wait
You should see messages similar to the following example.
Hello, universe! Greetings from your first Greengrass component.
Note
If the log messages don't change, the deployment failed or didn't reach the core device.
This can occur if your core device isn't connected to the internet or doesn't have permissions
to retrieve artifacts from your S3 bucket. Run the following command on your core device
to view the AWS IoT Greengrass Core software log file. This file includes logs from the
Greengrass core device's deployment service.
Linux or Unix
sudo tail -f /greengrass/v2/logs/greengrass.log
Windows Command Prompt (CMD)
type C:\greengrass\v2\logs\greengrass.log
The type command writes the file's contents to the terminal. Run this command
multiple times to observe changes in the file.
PowerShell
gc C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
For more information, see Troubleshooting AWS IoT Greengrass V2 (p. 911).
Next steps
You've completed this tutorial. The AWS IoT Greengrass Core software and your Hello World component
run on your device. Also, your Hello World component is available in the AWS IoT Greengrass cloud
service to deploy to other devices. For more information about the topics that this tutorial explores, see
the following:
• Create AWS IoT Greengrass components (p. 442)
60
AWS IoT Greengrass Developer Guide, Version 2
Next steps
• Publish components to deploy to your core devices (p. 451)
• Deploy AWS IoT Greengrass components to devices (p. 491)
61
AWS IoT Greengrass Developer Guide, Version 2
Supported platforms and requirements
Setting up AWS IoT Greengrass core
devices
Complete the tasks in this section to install, configure, and run the AWS IoT Greengrass Core software.
Note
This section describes advanced installation and configuration of the AWS IoT Greengrass Core
software. If you're a first-time user of AWS IoT Greengrass V2, we recommend that you first
complete the getting started tutorial (p. 31) to set up a core device and explore the features of
AWS IoT Greengrass.
Supported platforms and requirements
Before you begin, make sure you meet the following requirements to install and run the AWS IoT
Greengrass Core software.
Topics
• Supported platforms (p. 62)
• Device requirements (p. 63)
• Lambda function requirements (p. 64)
Supported platforms
AWS IoT Greengrass officially supports devices running the following platforms. Devices with platforms
not included in this list might work, but AWS IoT Greengrass tests on only these specified platforms.
Linux
Architectures:
• Armv7l
• Armv8 (AArch64)
• x86_64
Windows
Architectures:
• x86_64
Versions:
• Windows 10
• Windows Server 2019
62
AWS IoT Greengrass Developer Guide, Version 2
Device requirements
Note
Some AWS IoT Greengrass features aren't currently supported on Windows devices. For
more information, see Greengrass feature compatibility by operating system (p. 5) and
Feature considerations for Windows devices (p. 65).
Linux platforms can also run AWS IoT Greengrass V2 in a Docker container. For more information, see
Run AWS IoT Greengrass Core software in a Docker container (p. 131).
To build a custom Linux-based operating system, you can use the BitBake recipe for AWS IoT Greengrass
V2 in the meta-aws project. The meta-aws project provides recipes that you can use to build AWS edge
software capabilities in embedded Linux systems that are built with OpenEmbedded and Yocto Project
build frameworks. The Yocto Project is an open source collaboration project that helps you build custom
Linux-based systems for embedded applications regardless of hardware architecture. The BitBake recipe
for AWS IoT Greengrass V2 installs, configures, and automatically runs the AWS IoT Greengrass Core
software on your device.
Device requirements
Devices must meet the following requirements to install and run the AWS IoT Greengrass Core software
v2.x.
Note
You can use AWS IoT Device Tester for AWS IoT Greengrass to verify that your device can
run the AWS IoT Greengrass Core software and communicate with the AWS Cloud. For more
information, see Using AWS IoT Device Tester for AWS IoT Greengrass V2 (p. 817).
Linux
• Minimum 256 MB disk space available for the AWS IoT Greengrass Core software. This
requirement doesn't include components deployed to the core device.
• Minimum 96 MB RAM allocated to the AWS IoT Greengrass Core software. This requirement
doesn't include components that run on the core device. For more information, see Control
memory allocation with JVM options (p. 160).
• Java Runtime Environment (JRE) version 8 or greater. To use Java to develop custom components,
you must install a Java Development Kit (JDK). We recommend that you use Amazon Corretto 11
or OpenJDK 11.
• GNU C Library (glibc) version 2.25 or greater.
• The user that runs the AWS IoT Greengrass Core software (typically root), must have permission
to run sudo with any user and any group. The /etc/sudoers file must give this user permission
to run sudo as other groups. The permission for the user in /etc/sudoers should look like the
following example.
root ALL=(ALL:ALL) ALL
• The /tmp directory must be mounted with exec permissions.
• All of the following shell commands:
• ps -ax -o pid,ppid
• sudo
• sh
• kill
• cp
• chmod
• rm
• ln
63
AWS IoT Greengrass Developer Guide, Version 2
Lambda function requirements
• echo
• exit
• id
• uname
• grep
• Your device may also require the following optional shell commands:
• (Optional) systemctl (to set up the AWS IoT Greengrass Core software as a system service)
• (Optional) useradd, groupadd, and usermod (to set up the ggc_user system user and
ggc_group system group)
• (Optional) mkfifo (to run Lambda functions as components)
• To configure system resource limits for component processes, your device must run Linux kernel
version 2.6.24 or later.
• To run Lambda functions, your device must meet additional requirements. For more information,
see Lambda function requirements (p. 64).
Windows
• Minimum 256 MB disk space available for the AWS IoT Greengrass Core software. This
requirement doesn't include components deployed to the core device.
• Minimum 160 MB RAM allocated to the AWS IoT Greengrass Core software. This requirement
doesn't include components that run on the core device. For more information, see Control
memory allocation with JVM options (p. 160).
• Java Runtime Environment (JRE) version 8 or greater. To use Java to develop custom components,
you must install a Java Development Kit (JDK). We recommend Amazon Corretto 11 or OpenJDK
11.
Note
To use version 2.5.0 of the Greengrass nucleus (p. 181), you must use a 64-bit version
of the Java Runtime Environment (JRE). Greengrass nucleus version 2.5.1 supports 32-bit
and 64-bit JREs.
• Each user that runs component processes must exist in the LocalSystem account, and the user's
name and password must be in the Credential Manager instance for the LocalSystem account.
You can set up this user when you follow instructions to install the AWS IoT Greengrass Core
software (p. 67).
Lambda function requirements
Your device must meet the following requirements to run Lambda functions:
• A Linux-based operating system.
• You must run the AWS IoT Greengrass Core software as a root user. Use sudo, for example.
• Your device must have the mkfifo shell command.
• Your device must run the programming language libraries that a Lambda function requires. You must
install the required libraries on the device and add them to the PATH environment variable.
• Python version 3.8 for functions that use the Python 3.8 runtime.
• Python version 3.7 for functions that use the Python 3.7 runtime.
• Python version 2.7 for functions that use the Python 2.7 runtime.
• Node.js version 12.x for functions that use the Node.js 12.x runtime.
• Node.js version 10.x for functions that use the Node.js 10.x runtime.
• Java version 8 or later for functions that use the Java 8 runtime.
64
AWS IoT Greengrass Developer Guide, Version 2
Feature considerations for Windows devices
For more information about AWS IoT Greengrass support for Lambda runtimes, see Run AWS Lambda
functions (p. 523).
• To run containerized Lambda functions, your device must meet the following requirements:
• Linux kernel version 4.4 or later.
• The kernel must support cgroups, and you must enable and mount the following cgroups:
• The memory cgroup for AWS IoT Greengrass to set the memory limit for containerized Lambda
functions.
• The devices cgroup for containerized Lambda functions to access system devices or volumes.
• You must enable the following Linux kernel configurations on the device:
• Namespace:
• CONFIG_IPC_NS
• CONFIG_UTS_NS
• CONFIG_USER_NS
• CONFIG_PID_NS
• Cgroups:
• CONFIG_CGROUP_DEVICE
• CONFIG_CGROUPS
• CONFIG_MEMCG
• Others:
• CONFIG_POSIX_MQUEUE
• CONFIG_OVERLAY_FS
• CONFIG_HAVE_ARCH_SECCOMP_FILTER
• CONFIG_SECCOMP_FILTER
• CONFIG_KEYS
• CONFIG_SECCOMP
• CONFIG_SHMEM
Feature considerations for Windows devices
Some AWS IoT Greengrass features aren't currently supported on Windows devices. Review the following
considerations to confirm if a Windows device satisfies your feature requirements. For more information,
see Greengrass feature compatibility by operating system (p. 5).
• You can't run Lambda functions.
• You can't configure system resource limits to customize the maximum amount of CPU and RAM usage
that each component's processes can use on a core device.
• You can't pause and resume component processes using the PauseComponent (p. 605) and
ResumeComponent (p. 605) interprocess communication operations.
• The following AWS-provided components (p. 175) are not currently supported:
• Kinesis Data Firehose
• Lambda launcher
• Lambda manager
• Lambda runtimes
• Legacy subscription router
• Modbus-RTU protocol adapter
• Secure tunneling
65
AWS IoT Greengrass Developer Guide, Version 2
Set up an AWS account
• Amazon SNS
• AWS IoT SiteWise OPC-UA collector
• AWS IoT SiteWise publisher
• AWS IoT SiteWise processor
Set up an AWS account
If you do not have an AWS account, complete the following steps to create one.
To sign up for an AWS account
1. Open https://portal.aws.amazon.com/billing/signup.
2. Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call and entering a verification code on the
phone keypad.
To create an administrator user for yourself and add the user to an administrators group
(console)
1. Sign in to the IAM console as the account owner by choosing Root user and entering your AWS
account email address. On the next page, enter your password.
Note
We strongly recommend that you adhere to the best practice of using the Administrator
IAM user that follows and securely lock away the root user credentials. Sign in as the root
user only to perform a few account and service management tasks.
2. In the navigation pane, choose Users and then choose Add user.
3. For User name, enter Administrator.
4. Select the check box next to AWS Management Console access. Then select Custom password, and
then enter your new password in the text box.
5. (Optional) By default, AWS requires the new user to create a new password when first signing in. You
can clear the check box next to User must create a new password at next sign-in to allow the new
user to reset their password after they sign in.
6. Choose Next: Permissions.
7. Under Set permissions, choose Add user to group.
8. Choose Create group.
9. In the Create group dialog box, for Group name enter Administrators.
10. Choose Filter policies, and then select AWS managed - job function to filter the table contents.
11. In the policy list, select the check box for AdministratorAccess. Then choose Create group.
Note
You must activate IAM user and role access to Billing before you can use the
AdministratorAccess permissions to access the AWS Billing and Cost Management
console. To do this, follow the instructions in step 1 of the tutorial about delegating access
to the billing console.
12. Back in the list of groups, select the check box for your new group. Choose Refresh if necessary to
see the group in the list.
13. Choose Next: Tags.
14. (Optional) Add metadata to the user by attaching tags as key-value pairs. For more information
about using tags in IAM, see Tagging IAM entities in the IAM User Guide.
66
AWS IoT Greengrass Developer Guide, Version 2
Install the AWS IoT Greengrass Core software
15. Choose Next: Review to see the list of group memberships to be added to the new user. When you
are ready to proceed, choose Create user.
You can use this same process to create more groups and users and to give your users access to your AWS
account resources. To learn about using policies that restrict user permissions to specific AWS resources,
see Access management and Example policies.
Install the AWS IoT Greengrass Core software
AWS IoT Greengrass extends AWS to edge devices so that they can act on the data they generate, while
they use the AWS Cloud for management, analytics, and durable storage. Install the AWS IoT Greengrass
Core software on edge devices to integrate with AWS IoT Greengrass and the AWS Cloud.
Important
Before you download and install the AWS IoT Greengrass Core software, check that your core
device meets the requirements (p. 63) to install and run the AWS IoT Greengrass Core
software v2.0.
The AWS IoT Greengrass Core software includes an installer that sets up your device as a Greengrass
core device. When you run the installer, you can configure options, such as the root folder and the AWS
Region to use. You can choose to have the installer create required AWS IoT and IAM resources for you.
You can also choose to deploy local development tools to configure a device that you use for custom
component development.
The AWS IoT Greengrass Core software requires the following AWS IoT and IAM resources to connect to
the AWS Cloud and operate:
• An AWS IoT thing. When you register a device as an AWS IoT thing, that device can use a digital
certificate to authenticate with AWS. This certificate allows the device to communicate with AWS IoT
and AWS IoT Greengrass. For more information, see Device authentication and authorization for AWS
IoT Greengrass (p. 773).
• (Optional) An AWS IoT thing group. You use thing groups to manage fleets of Greengrass core devices.
When you deploy software components to your devices, you can choose to deploy to individual devices
or to groups of devices. You can add a device to a thing group to deploy that thing group's software
components to the device. For more information, see Deploy AWS IoT Greengrass components to
devices (p. 491).
• An IAM role. Greengrass core devices use the AWS IoT Core credentials provider to authorize calls
to AWS services with an IAM role. This role allows your device to interact with AWS IoT, send logs
to Amazon CloudWatch Logs, and download custom component artifacts from Amazon Simple
Storage Service (Amazon S3). For more information, see Authorize core devices to interact with AWS
services (p. 790).
• An AWS IoT role alias. Greengrass core devices use the role alias to identify the IAM role to use. The
role alias enables you to change the IAM role but keep the device configuration the same. For more
information, see Authorizing direct calls to AWS services in the AWS IoT Core Developer Guide.
Choose one of the following options to install the AWS IoT Greengrass Core software on your core
device.
• Quick installation
Choose this option to set up a Greengrass core device in as few steps as possible. The installer creates
the required AWS IoT and IAM resources for you. This option requires you to provide AWS credentials
to the installer to create resources in your AWS account.
67
AWS IoT Greengrass Developer Guide, Version 2
Install the AWS IoT Greengrass Core software
You can't use this option to install behind a firewall or network proxy. If your devices are behind a
firewall or network proxy, consider manual installation (p. 76).
For more information, see Install AWS IoT Greengrass Core software with automatic resource
provisioning (p. 69).
• Manual installation
Choose this option to create the required AWS resources manually or to install behind a firewall or
network proxy. By using a manual installation, you don't need to give the installer permission to create
resources in your AWS account, because you create the required AWS IoT and IAM resources. You can
also configure your device to connect on port 443 or through a network proxy.
For more information, see Install AWS IoT Greengrass Core software with manual resource
provisioning (p. 76).
• Installation with AWS IoT fleet provisioning
Choose this option to create the required AWS resources from an AWS IoT fleet provisioning template.
You might choose this option to create similar devices in a fleet, or if you manufacture devices that
your customers later activate, such as vehicles or smart home devices. Devices use claim certificates
to authenticate and provision AWS resources, including an X.509 client certificate that the device
uses to connect to the AWS Cloud for normal operation. You can embed or flash the claim certificates
into the device's hardware during manufacturing, and you can use the same claim certificate and key
to provision multiple devices. You can also configure devices to connect on port 443 or through a
network proxy.
For more information, see Install AWS IoT Greengrass Core software with AWS IoT fleet
provisioning (p. 92).
• Installation with custom provisioning
Choose this option to develop a custom Java application that provisions the required AWS resources.
You might choose this option if you create your own X.509 client certificates or if you want more
control over the provisioning process. AWS IoT Greengrass provides an interface that you can
implement to exchange information between your custom provisioning application and the AWS IoT
Greengrass Core software installer.
For more information, see Install AWS IoT Greengrass Core software with custom resource
provisioning (p. 117).
AWS IoT Greengrass also provides containerized environments that run the AWS IoT Greengrass Core
software. You can use a Dockerfile to run AWS IoT Greengrass in a Docker container (p. 131).
Topics
• Install AWS IoT Greengrass Core software with automatic resource provisioning (p. 69)
• Install AWS IoT Greengrass Core software with manual resource provisioning (p. 76)
• Install AWS IoT Greengrass Core software with AWS IoT fleet provisioning (p. 92)
• Install AWS IoT Greengrass Core software with custom resource provisioning (p. 117)
• Installer arguments (p. 126)
68
AWS IoT Greengrass Developer Guide, Version 2
Install with automatic provisioning
Install AWS IoT Greengrass Core software with
automatic resource provisioning
The AWS IoT Greengrass Core software includes an installer that sets up your device as a Greengrass core
device. To set up a device quickly, the installer can provision the AWS IoT thing, AWS IoT thing group,
IAM role, and AWS IoT role alias that the core device requires to operate. The installer can also deploy
the local development tools to the core device, so you can use the device to develop and test custom
software components. The installer requires AWS credentials to provision these resources and create the
deployment.
If you can't provide AWS credentials to the device, you can provision the AWS resources that the core
device requires to operate. You can also deploy the development tools to a core device to use as a
development device. This enables you to provide fewer permissions to the device when you run the
installer. For more information, see Install AWS IoT Greengrass Core software with manual resource
provisioning (p. 76).
Important
Before you download the AWS IoT Greengrass Core software, check that your core device meets
the requirements (p. 63) to install and run the AWS IoT Greengrass Core software v2.0.
Topics
• Set up the device environment (p. 69)
• Provide AWS credentials to the device (p. 71)
• Download the AWS IoT Greengrass Core software (p. 72)
• Install the AWS IoT Greengrass Core software (p. 73)
Set up the device environment
Follow the steps in this section to set up a Linux or Windows device to use as your AWS IoT Greengrass
core device.
Set up a Linux device
To set up a Linux device for AWS IoT Greengrass V2
1. Install the Java runtime, which AWS IoT Greengrass Core software requires to run. We recommend
that you use Amazon Corretto 11 or OpenJDK 11.. The following commands show you how to install
OpenJDK on your device.
• For Debian-based or Ubuntu-based distributions:
sudo apt install default-jdk
• For Red Hat-based distributions:
sudo yum install java-11-openjdk-devel
When the installation completes, run the following command to verify that Java runs on your
Raspberry Pi.
java -version
69
AWS IoT Greengrass Developer Guide, Version 2
Install with automatic provisioning
The command prints the version of Java that runs on the device. For example, on a Debian-based
distribution, the output might look similar to the following sample.
openjdk version "11.0.9.1" 2020-11-04
OpenJDK Runtime Environment (build 11.0.9.1+1-post-Debian-1deb10u2)
OpenJDK 64-Bit Server VM (build 11.0.9.1+1-post-Debian-1deb10u2, mixed mode)
2. (Optional) Create the default system user and group that runs components on your device. You can
also choose to let the AWS IoT Greengrass Core software installer create this user and group during
installation with the --component-default-user installer argument. For more information, see
Installer arguments (p. 126).
sudo adduser --system ggc_user
sudo addgroup --system ggc_group
3. Verify that the user that runs the AWS IoT Greengrass Core software (typically root), has permission
to run sudo with any user and any group.
a. Open the /etc/sudoers file.
b. Verify that the permission for the user looks like the following example.
root ALL=(ALL:ALL) ALL
4. Install all other required dependencies on your device as indicated by the list of requirements in
Device requirements (p. 63).
Set up a Windows device
Note
This feature is available for v2.5.0 and later of the Greengrass nucleus component (p. 181).
To set up a Windows device for AWS IoT Greengrass V2
1. Install the Java runtime, which AWS IoT Greengrass Core software requires to run. We recommend
that you use Amazon Corretto 11 or OpenJDK 11..
2. Open the Windows Command Prompt (cmd.exe) as an administrator.
3. Create the default user in the LocalSystem account on the Windows device. Replace password with
a secure password.
net user /add ggc_user password
4. Download and install the PsExec utility from Microsoft on the device.
5. Use the PsExec utility to store the user name and password for the default user in the Credential
Manager instance for the LocalSystem account. Replace password with the user's password that you
set earlier.
psexec -s cmd /c cmdkey /generic:ggc_user /user:ggc_user /pass:password
If the PsExec License Agreement opens, choose Accept to agree to the license and run the
command.
Note
On Windows devices, the LocalSystem account runs the Greengrass nucleus, and you must
use the PsExec utility to store the default user information in the LocalSystem account.
Using the Credential Manager application stores this information in the Windows account of
the currently logged on user, instead of the LocalSystem account.
70
AWS IoT Greengrass Developer Guide, Version 2
Install with automatic provisioning
Provide AWS credentials to the device
Provide your AWS credentials to your device so that the installer can provision the required AWS
resources. For more information about the required permissions, see Minimal IAM policy for installer to
provision resources (p. 793).
To provide AWS credentials to the device
• Provide your AWS credentials to the device so that the installer can provision the AWS IoT and IAM
resources for your core device. To increase security, you can get credentials for an IAM role that
allows only the minimum permissions necessary to provision. For more information, see Minimal IAM
policy for installer to provision resources (p. 793).
Note
The installer doesn't save or store your credentials.
On your device, do one of the following to retrieve credentials and make them available to the AWS
IoT Greengrass Core software installer:
• Use long-term credentials from an IAM user:
a. Provide the access key ID and secret access key for your IAM user. For more information
about how to retrieve long-term credentials, see Managing access keys for IAM users in the
IAM User Guide.
b. Run the following commands to provide the credentials to the AWS IoT Greengrass Core
software.
Linux or Unix
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Windows Command Prompt (CMD)
set AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
set AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
PowerShell
$env:AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
$env:AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
• (Recommended) Use temporary security credentials from an IAM role:
a. Provide the access key ID, secret access key, and session token from an IAM role that you
assume. For more information about how to retrieve these credentials, see Using temporary
security credentials with the AWS CLI in the IAM User Guide.
b. Run the following commands to provide the credentials to the AWS IoT Greengrass Core
software.
Linux or Unix
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_SESSION_TOKEN=AQoDYXdzEJr1K...o5OytwEXAMPLE=
71
AWS IoT Greengrass Developer Guide, Version 2
Install with automatic provisioning
Windows Command Prompt (CMD)
set AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
set AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
set AWS_SESSION_TOKEN=AQoDYXdzEJr1K...o5OytwEXAMPLE=
PowerShell
$env:AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
$env:AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
$env:AWS_SESSION_TOKEN="AQoDYXdzEJr1K...o5OytwEXAMPLE="
Download the AWS IoT Greengrass Core software
You can download the latest version of the AWS IoT Greengrass Core software from the following
location:
• https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip
Note
You can download a specific version of the AWS IoT Greengrass Core software from the
following location. Replace version with the version to download.
https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-version.zip
To download the AWS IoT Greengrass Core software
1. On your core device, download the AWS IoT Greengrass Core software to a file named
greengrass-nucleus-latest.zip.
Linux or Unix
curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-
latest.zip > greengrass-nucleus-latest.zip
Windows Command Prompt (CMD)
curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-
latest.zip > greengrass-nucleus-latest.zip
PowerShell
iwr -Uri https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-
latest.zip -OutFile greengrass-nucleus-latest.zip
By downloading this software, you agree to the Greengrass Core Software License Agreement.
2. Unzip the AWS IoT Greengrass Core software to a folder on your device. Replace
GreengrassInstaller with the folder that you want to use.
72
AWS IoT Greengrass Developer Guide, Version 2
Install with automatic provisioning
Linux or Unix
unzip greengrass-nucleus-latest.zip -d GreengrassInstaller && rm greengrass-
nucleus-latest.zip
Windows Command Prompt (CMD)
mkdir GreengrassInstaller && tar -xf greengrass-nucleus-latest.zip -
C GreengrassInstaller && del greengrass-nucleus-latest.zip
PowerShell
Expand-Archive -Path greengrass-nucleus-latest.zip -DestinationPath .
\GreengrassInstaller
rm greengrass-nucleus-latest.zip
3. (Optional) Run the following command to see the version of the AWS IoT Greengrass Core software.
java -jar ./GreengrassInstaller/lib/Greengrass.jar --version
Important
If you install a version of the Greengrass nucleus earlier than v2.4.0, don't remove this folder
after you install the AWS IoT Greengrass Core software. The AWS IoT Greengrass Core software
uses the files in this folder to run.
If you downloaded the latest version of the software, you install v2.4.0 or later, and you can
remove this folder after you install the AWS IoT Greengrass Core software.
Install the AWS IoT Greengrass Core software
Run the installer with arguments that specify to do the following:
• Create the AWS resources that the core device requires to operate.
• Specify to use the ggc_user system user to run software components on the core device. On Linux
devices, this command also specifies to use the ggc_group system group, and the installer creates the
system user and group for you.
• Set up the AWS IoT Greengrass Core software as a system service that runs as boot. On Linux devices,
this requires the Systemd init system.
To set up a development device with local development tools, specify the --deploy-dev-tools
true argument. The local development tools can take up to a minute to deploy after the installation
completes.
For more information about the arguments that you can specify, see Installer arguments (p. 126).
Note
If you are running AWS IoT Greengrass on a device with limited memory, you can control the
amount of memory that AWS IoT Greengrass Core software uses. To control memory allocation,
you can set JVM heap size options in the jvmOptions configuration parameter in your nucleus
component. For more information, see Control memory allocation with JVM options (p. 160).
To install the AWS IoT Greengrass Core software
1. Run the AWS IoT Greengrass Core installer. Replace argument values in your command as follows.
73
AWS IoT Greengrass Developer Guide, Version 2
Install with automatic provisioning
a. /greengrass/v2 or C:\greengrass\v2: The path to the root folder to use to install the AWS
IoT Greengrass Core software.
b. GreengrassInstaller. The path to the folder where you unpacked the AWS IoT Greengrass
Core software installer.
c. region. The AWS Region in which to find or create resources.
d. MyGreengrassCore. The name of the AWS IoT thing for your Greengrass core device. If
the thing doesn't exist, the installer creates it. The installer downloads the certificates to
authenticate as the AWS IoT thing. For more information, see Device authentication and
authorization for AWS IoT Greengrass (p. 773).
Note
The thing name can't contain colon (:) characters.
e. MyGreengrassCoreGroup. The name of AWS IoT thing group for your Greengrass core device.
If the thing group doesn't exist, the installer creates it and adds the thing to it. If the thing
group exists and has an active deployment, the core device downloads and runs the software
that the deployment specifies.
Note
The thing group name can't contain colon (:) characters.
f. GreengrassV2IoTThingPolicy. The name of the AWS IoT policy that allows the Greengrass
core devices to communicate with AWS IoT and AWS IoT Greengrass. If the AWS IoT policy
doesn't exist, the installer creates a permissive AWS IoT policy with this name. You can restrict
this policy's permissions for you use case. For more information, see Minimal AWS IoT policy for
AWS IoT Greengrass V2 core devices (p. 777).
g. GreengrassV2TokenExchangeRole. The name of the IAM role that allows the Greengrass
core device to get temporary AWS credentials. If the role doesn't exist, the installer creates it
and creates and attaches a policy named GreengrassV2TokenExchangeRoleAccess. For
more information, see Authorize core devices to interact with AWS services (p. 790).
h. GreengrassCoreTokenExchangeRoleAlias. The alias to the IAM role that allows the
Greengrass core device to get temporary credentials later. If the role alias doesn't exist, the
installer creates it and points it to the IAM role that you specify. For more information, see
Authorize core devices to interact with AWS services (p. 790).
Linux or Unix
sudo -E java -Droot="/greengrass/v2" -Dlog.store=FILE \
-jar ./GreengrassInstaller/lib/Greengrass.jar \
--aws-region region \
--thing-name MyGreengrassCore \
--thing-group-name MyGreengrassCoreGroup \
--thing-policy-name GreengrassV2IoTThingPolicy \
--tes-role-name GreengrassV2TokenExchangeRole \
--tes-role-alias-name GreengrassCoreTokenExchangeRoleAlias \
--component-default-user ggc_user:ggc_group \
--provision true \
--setup-system-service true
Windows Command Prompt (CMD)
java -Droot="C:\greengrass\v2" "-Dlog.store=FILE" ^
-jar ./GreengrassInstaller/lib/Greengrass.jar ^
--aws-region region ^
--thing-name MyGreengrassCore ^
--thing-group-name MyGreengrassCoreGroup ^
--thing-policy-name GreengrassV2IoTThingPolicy ^
--tes-role-name GreengrassV2TokenExchangeRole ^
74
AWS IoT Greengrass Developer Guide, Version 2
Install with automatic provisioning
--tes-role-alias-name GreengrassCoreTokenExchangeRoleAlias ^
--component-default-user ggc_user ^
--provision true ^
--setup-system-service true
PowerShell
java -Droot="C:\greengrass\v2" "-Dlog.store=FILE" `
-jar ./GreengrassInstaller/lib/Greengrass.jar `
--aws-region region `
--thing-name MyGreengrassCore `
--thing-group-name MyGreengrassCoreGroup `
--thing-policy-name GreengrassV2IoTThingPolicy `
--tes-role-name GreengrassV2TokenExchangeRole `
--tes-role-alias-name GreengrassCoreTokenExchangeRoleAlias `
--component-default-user ggc_user `
--provision true `
--setup-system-service true
The installer prints the following messages if it succeeds:
• If you specify --provision, the installer prints Successfully configured Nucleus with
provisioned resource details if it configured the resources successfully.
• If you specify --deploy-dev-tools, the installer prints Configured Nucleus to deploy
aws.greengrass.Cli component if it created the deployment successfully.
• If you specify --setup-system-service true, the installer prints Successfully set up
Nucleus as a system service if it set up and ran the software as a service.
• If you don't specify --setup-system-service true, the installer prints Launched Nucleus
successfully if it succeeded and ran the software.
2. Skip this step if you installed Greengrass nucleus (p. 181) v2.0.4 or later. If you downloaded the
latest version of the software, you installed v2.0.4 or later.
Run the following command to set the required file permissions for your AWS IoT Greengrass Core
software root folder. Replace /greengrass/v2 with the root folder that you specified in your
installation command, and replace /greengrass with the parent folder for your root folder.
sudo chmod 755 /greengrass/v2 && sudo chmod 755 /greengrass
If you installed the AWS IoT Greengrass Core software as a system service, the installer runs the software
for you. Otherwise, you must run the software manually. For more information, see Run the AWS IoT
Greengrass Core software (p. 128).
Note
By default, the IAM role that the installer creates doesn't allow access to component artifacts
in S3 buckets. To deploy custom components that define artifacts in Amazon S3, you must add
permissions to the role to allow your core device to retrieve component artifacts. For more
information, see Allow access to S3 buckets for component artifacts (p. 792).
If you don't yet have an S3 bucket for component artifacts, you can add these permissions later
after you create a bucket.
For more information about how to configure and use the software and AWS IoT Greengrass, see the
following:
• Configure the AWS IoT Greengrass Core software (p. 157)
• Develop AWS IoT Greengrass components (p. 440)
• Deploy AWS IoT Greengrass components to devices (p. 491)
75
AWS IoT Greengrass Developer Guide, Version 2
Install with manual provisioning
• Greengrass Command Line Interface (p. 428)
Install AWS IoT Greengrass Core software with
manual resource provisioning
The AWS IoT Greengrass Core software includes an installer that sets up your device as a Greengrass
core device. To set up a device manually, you can create the required AWS IoT and IAM resources for the
device to use. If you create these resources manually, you don't need to provide AWS credentials to the
installer.
When you manually install the AWS IoT Greengrass Core software, you can also configure the device
to use a network proxy or connect to AWS on port 443. You might need to specify these configuration
options if your device runs behind a firewall or a network proxy, for example. For more information, see
Connect on port 443 or through a network proxy (p. 165).
Important
Before you download the AWS IoT Greengrass Core software, check that your core device meets
the requirements (p. 63) to install and run the AWS IoT Greengrass Core software v2.0.
Topics
• Create an AWS IoT thing (p. 76)
• Retrieve AWS IoT endpoints (p. 80)
• Create a token exchange role (p. 80)
• Download certificates to the device (p. 84)
• Set up the device environment (p. 69)
• Download the AWS IoT Greengrass Core software (p. 72)
• Install the AWS IoT Greengrass Core software (p. 89)
Create an AWS IoT thing
AWS IoT things represent devices and logical entities that connect to AWS IoT. Greengrass core devices
are AWS IoT things. When you register a device as an AWS IoT thing, that device can use a digital
certificate to authenticate with AWS. This certificate allows the device to communicate with AWS IoT and
AWS IoT Greengrass.
In this section, you create an AWS IoT thing and download certificates that your device can use to
connect to AWS.
To create an AWS IoT thing
1. Create an AWS IoT thing for your device. On your development computer, run the following
command.
• Replace MyGreengrassCore with the thing name to use. This name is also the name of your
Greengrass core device.
Note
The thing name can't contain colon (:) characters.
aws iot create-thing --thing-name MyGreengrassCore
The response looks similar to the following example, if the request succeeds.
76
AWS IoT Greengrass Developer Guide, Version 2
Install with manual provisioning
{
"thingName": "MyGreengrassCore",
"thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyGreengrassCore",
"thingId": "8cb4b6cd-268e-495d-b5b9-1713d71dbf42"
}
2. Create a folder where you download the certificates for the AWS IoT thing.
mkdir greengrass-v2-certs
3. Create and download the certificates for the AWS IoT thing.
aws iot create-keys-and-certificate --set-as-active --certificate-pem-outfile
greengrass-v2-certs/device.pem.crt --public-key-outfile greengrass-v2-certs/
public.pem.key --private-key-outfile greengrass-v2-certs/private.pem.key
The response looks similar to the following example, if the request succeeds.
{
"certificateArn": "arn:aws:iot:us-west-2:123456789012:cert/
aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4",
"certificateId": "aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4",
"certificatePem": "-----BEGIN CERTIFICATE-----
MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w
0BAQUFADCBiDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZ
WF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIw
EAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5
jb20wHhcNMTEwNDI1MjA0NTIxWhcNMTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBh
MCVVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBb
WF6b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMx
HzAdBgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5jb20wgZ8wDQYJKoZIhvcNAQE
BBQADgY0AMIGJAoGBAMaK0dn+a4GmWIWJ21uUSfwfEvySWtC2XADZ4nB+BLYgVI
k60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9TrDHudUZg3qX4waLG5M43q7Wgc/MbQ
ITxOUSQv7c7ugFFDzQGBzZswY6786m86gpEIbb3OhjZnzcvQAaRHhdlQWIMm2nr
AgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4nUhVVxYUntneD9+h8Mg9q6q+auN
KyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0FkbFFBjvSfpJIlJ00zbhNYS5f6Guo
EDmFJl0ZxBHjJnyp378OD8uTs7fLvjx79LjSTbNYiytVbZPQUQ5Yaxu2jXnimvw
3rrszlaEXAMPLE=
-----END CERTIFICATE-----",
"keyPair": {
"PublicKey": "-----BEGIN PUBLIC KEY-----
\nMIIBIjANBgkqhkEXAMPLEQEFAAOCAQ8AMIIBCgKCAQEAEXAMPLE1nnyJwKSMHw4h
\nMMEXAMPLEuuN/dMAS3fyce8DW/4+EXAMPLEyjmoF/YVF/
gHr99VEEXAMPLE5VF13\n59VK7cEXAMPLE67GK+y+jikqXOgHh/xJTwo
+sGpWEXAMPLEDz18xOd2ka4tCzuWEXAMPLEahJbYkCPUBSU8opVkR7qkEXAMPLE1DR6sx2HocliOOLtu6Fkw91swQWEXAMPLE
\GB3ZPrNh0PzQYvjUStZeccyNCx2EXAMPLEvp9mQOUXP6plfgxwKRX2fEXAMPLEDa\nhJLXkX3rHU2xbxJSq7D
+XEXAMPLEcw+LyFhI5mgFRl88eGdsAEXAMPLElnI9EesG\nFQIDAQAB\n-----END PUBLIC KEY-----\n",
"PrivateKey": "-----BEGIN RSA PRIVATE KEY-----\nkey omitted for security reasons
\n-----END RSA PRIVATE KEY-----\n"
}
}
4. Attach the certificate to the AWS IoT thing.
• Replace MyGreengrassCore with the name of your AWS IoT thing.
• Replace the certificate Amazon Resource Name (ARN) with the ARN of the certificate that you
created in the previous step.
77
AWS IoT Greengrass Developer Guide, Version 2
Install with manual provisioning
aws iot attach-thing-principal --thing-name MyGreengrassCore
--principal arn:aws:iot:us-west-2:123456789012:cert/
aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4
The command doesn't have any output if the request succeeds.
5. Create and attach an AWS IoT policy that defines the AWS IoT permissions for your Greengrass core
device. The following policy allows access to all MQTT topics and Greengrass operations, so your
device works with custom applications and future changes that require new Greengrass operations.
You can restrict this policy down based on your use case. For more information, see Minimal AWS IoT
policy for AWS IoT Greengrass V2 core devices (p. 777).
If you have set up a Greengrass core device before, you can attach its AWS IoT policy instead of
creating a new one.
Do the following:
a. Create a file that contains the AWS IoT policy document that Greengrass core devices require.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano greengrass-v2-iot-policy.json
Copy the following JSON into the file.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish",
"iot:Subscribe",
"iot:Receive",
"iot:Connect",
"greengrass:*"
],
"Resource": [
"*"
]
}
]
}
b. Create an AWS IoT policy from the policy document.
• Replace GreengrassV2IoTThingPolicy with the name of the policy to create.
aws iot create-policy --policy-name GreengrassV2IoTThingPolicy --policy-document
file://greengrass-v2-iot-policy.json
The response looks similar to the following example, if the request succeeds.
{
"policyName": "GreengrassV2IoTThingPolicy",
78
AWS IoT Greengrass Developer Guide, Version 2
Install with manual provisioning
"policyArn": "arn:aws:iot:us-west-2:123456789012:policy/
GreengrassV2IoTThingPolicy",
"policyDocument": "{
\"Version\": \"2012-10-17\",
\"Statement\": [
{
\"Effect\": \"Allow\",
\"Action\": [
\"iot:Publish\",
\"iot:Subscribe\",
\"iot:Receive\",
\"iot:Connect\",
\"greengrass:*\"
],
\"Resource\": [
\"*\"
]
}
]
}",
"policyVersionId": "1"
}
c. Attach the AWS IoT policy to the AWS IoT thing's certificate.
• Replace GreengrassV2IoTThingPolicy with the name of the policy to attach.
• Replace the target ARN with the ARN of the certificate for your AWS IoT thing.
aws iot attach-policy --policy-name GreengrassV2IoTThingPolicy
--target arn:aws:iot:us-west-2:123456789012:cert/
aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4
The command doesn't have any output if the request succeeds.
6. (Optional) Add the AWS IoT thing to a new or existing thing group. You use thing groups to manage
fleets of Greengrass core devices. When you deploy software components to your devices, you can
choose to target individual devices or groups of devices. You can add a device to a thing group with
an active Greengrass deployment to deploy that thing group's software components to the device.
Do the following:
a. (Optional) Create an AWS IoT thing group.
• Replace MyGreengrassCoreGroup with the name of the thing group to create.
Note
The thing group name can't contain colon (:) characters.
aws iot create-thing-group --thing-group-name MyGreengrassCoreGroup
The response looks similar to the following example, if the request succeeds.
{
"thingGroupName": "MyGreengrassCoreGroup",
"thingGroupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/
MyGreengrassCoreGroup",
"thingGroupId": "4df721e1-ff9f-4f97-92dd-02db4e3f03aa"
}
b. Add the AWS IoT thing to a thing group.
79
AWS IoT Greengrass Developer Guide, Version 2
Install with manual provisioning
• Replace MyGreengrassCore with the name of your AWS IoT thing.
• Replace MyGreengrassCoreGroup with the name of the thing group.
aws iot add-thing-to-thing-group --thing-name MyGreengrassCore --thing-group-
name MyGreengrassCoreGroup
The command doesn't have any output if the request succeeds.
Retrieve AWS IoT endpoints
Get the AWS IoT endpoints for your AWS account, and save them to use later. Your device uses these
endpoints to connect to AWS IoT. Do the following:
1. Get the AWS IoT data endpoint for your AWS account.
aws iot describe-endpoint --endpoint-type iot:Data-ATS
The response looks similar to the following example, if the request succeeds.
{
"endpointAddress": "device-data-prefix-ats.iot.us-west-2.amazonaws.com"
}
2. Get the AWS IoT credentials endpoint for your AWS account.
aws iot describe-endpoint --endpoint-type iot:CredentialProvider
The response looks similar to the following example, if the request succeeds.
{
"endpointAddress": "device-credentials-prefix.credentials.iot.us-
west-2.amazonaws.com"
}
Create a token exchange role
Greengrass core devices use an IAM service role, called the token exchange role, to authorize calls to AWS
services. The device uses the AWS IoT credentials provider to get temporary AWS credentials for this role,
which allows the device to interact with AWS IoT, send logs to Amazon CloudWatch Logs, and download
custom component artifacts from Amazon S3. For more information, see Authorize core devices to
interact with AWS services (p. 790).
You use an AWS IoT role alias to configure the token exchange role for Greengrass core devices. Role
aliases enable you to change the token exchange role for a device but keep the device configuration the
same. For more information, see Authorizing direct calls to AWS services in the AWS IoT Core Developer
Guide.
In this section, you create a token exchange IAM role and an AWS IoT role alias that points to the role.
If you have already set up a Greengrass core device, you can use its token exchange role and role alias
instead of creating new ones. Then, you configure your device's AWS IoT thing to use that role and alias.
80
AWS IoT Greengrass Developer Guide, Version 2
Install with manual provisioning
To create a token exchange IAM role
1. Create an IAM role that your device can use as a token exchange role. Do the following:
a. Create a file that contains the trust policy document that the token exchange role requires.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano device-role-trust-policy.json
Copy the following JSON into the file.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "credentials.iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
b. Create the token exchange role with the trust policy document.
• Replace GreengrassV2TokenExchangeRole with the name of the IAM role to create.
aws iam create-role --role-name GreengrassV2TokenExchangeRole --assume-role-policy-
document file://device-role-trust-policy.json
The response looks similar to the following example, if the request succeeds.
{
"Role": {
"Path": "/",
"RoleName": "GreengrassV2TokenExchangeRole",
"RoleId": "AROAZ2YMUHYHK5OKM77FB",
"Arn": "arn:aws:iam::123456789012:role/GreengrassV2TokenExchangeRole",
"CreateDate": "2021-02-06T00:13:29+00:00",
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "credentials.iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
}
c. Create a file that contains the access policy document that the token exchange role requires.
81
AWS IoT Greengrass Developer Guide, Version 2
Install with manual provisioning
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano device-role-access-policy.json
Copy the following JSON into the file.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:DescribeCertificate",
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:DescribeLogStreams",
"s3:GetBucketLocation"
],
"Resource": "*"
}
]
}
Note
This access policy doesn't allow access to component artifacts in S3 buckets. To deploy
custom components that define artifacts in Amazon S3, you must add permissions
to the role to allow your core device to retrieve component artifacts. For more
information, see Allow access to S3 buckets for component artifacts (p. 792).
If you don't yet have an S3 bucket for component artifacts, you can add these
permissions later after you create a bucket.
d. Create the IAM policy from the policy document.
• Replace GreengrassV2TokenExchangeRoleAccess with the name of the IAM policy to
create.
aws iam create-policy --policy-name GreengrassV2TokenExchangeRoleAccess --policy-
document file://device-role-access-policy.json
The response looks similar to the following example, if the request succeeds.
{
"Policy": {
"PolicyName": "GreengrassV2TokenExchangeRoleAccess",
"PolicyId": "ANPAZ2YMUHYHACI7C5Z66",
"Arn": "arn:aws:iam::123456789012:policy/GreengrassV2TokenExchangeRoleAccess",
"Path": "/",
"DefaultVersionId": "v1",
"AttachmentCount": 0,
"PermissionsBoundaryUsageCount": 0,
"IsAttachable": true,
"CreateDate": "2021-02-06T00:37:17+00:00",
"UpdateDate": "2021-02-06T00:37:17+00:00"
}
}
82
AWS IoT Greengrass Developer Guide, Version 2
Install with manual provisioning
e. Attach the IAM policy to the token exchange role.
• Replace GreengrassV2TokenExchangeRole with the name of the IAM role.
• Replace the policy ARN with the ARN of the IAM policy that you created in the previous step.
aws iam attach-role-policy --role-name GreengrassV2TokenExchangeRole --policy-
arn arn:aws:iam::123456789012:policy/GreengrassV2TokenExchangeRoleAccess
The command doesn't have any output if the request succeeds.
2. Create an AWS IoT role alias that points to the token exchange role.
• Replace GreengrassCoreTokenExchangeRoleAlias with the name of the role alias to create.
• Replace the role ARN with the ARN of the IAM role that you created in the previous step.
aws iot create-role-alias --role-alias GreengrassCoreTokenExchangeRoleAlias --role-
arn arn:aws:iam::123456789012:role/GreengrassV2TokenExchangeRole
The response looks similar to the following example, if the request succeeds.
{
"roleAlias": "GreengrassCoreTokenExchangeRoleAlias",
"roleAliasArn": "arn:aws:iot:us-west-2:123456789012:rolealias/
GreengrassCoreTokenExchangeRoleAlias"
}
Note
To create a role alias, you must have permission to pass the token exchange IAM role to
AWS IoT. If you receive an error message when you try to create a role alias, check that your
AWS user has this permission. For more information, see Granting a user permissions to
pass a role to an AWS service in the AWS Identity and Access Management User Guide.
3. Create and attach an AWS IoT policy that allows your Greengrass core device to use the role alias to
assume the token exchange role. If you have set up a Greengrass core device before, you can attach
its role alias AWS IoT policy instead of creating a new one. Do the following:
a. (Optional) Create a file that contains the AWS IoT policy document that the role alias requires.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano greengrass-v2-iot-role-alias-policy.json
Copy the following JSON into the file.
• Replace the resource ARN with the ARN of your role alias.
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:AssumeRoleWithCertificate",
"Resource": "arn:aws:iot:us-west-2:123456789012:rolealias/
GreengrassCoreTokenExchangeRoleAlias"
83
AWS IoT Greengrass Developer Guide, Version 2
Install with manual provisioning
}
]
}
b. Create an AWS IoT policy from the policy document.
• Replace GreengrassCoreTokenExchangeRoleAliasPolicy with the name of the AWS
IoT policy to create.
aws iot create-policy --policy-name GreengrassCoreTokenExchangeRoleAliasPolicy --
policy-document file://greengrass-v2-iot-role-alias-policy.json
The response looks similar to the following example, if the request succeeds.
{
"policyName": "GreengrassCoreTokenExchangeRoleAliasPolicy",
"policyArn": "arn:aws:iot:us-west-2:123456789012:policy/
GreengrassCoreTokenExchangeRoleAliasPolicy",
"policyDocument": "{
\"Version\":\"2012-10-17\",
\"Statement\": [
{
\"Effect\": \"Allow\",
\"Action\": \"iot:AssumeRoleWithCertificate\",
\"Resource\": \"arn:aws:iot:us-west-2:123456789012:rolealias/
GreengrassCoreTokenExchangeRoleAlias\"
}
]
}",
"policyVersionId": "1"
}
c. Attach the AWS IoT policy to the AWS IoT thing's certificate.
• Replace GreengrassCoreTokenExchangeRoleAliasPolicy with the name of the role
alias AWS IoT policy.
• Replace the target ARN with the ARN of the certificate for your AWS IoT thing.
aws iot attach-policy --policy-name GreengrassCoreTokenExchangeRoleAliasPolicy
--target arn:aws:iot:us-west-2:123456789012:cert/
aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4
The command doesn't have any output if the request succeeds.
Download certificates to the device
Earlier, you downloaded your device's certificates to your development computer. In this section, you
copy these certificates to your device set up the device with the certificates that it uses to connect to
AWS IoT.
To download certificates to the device
1. Copy the AWS IoT thing certificates from your development computer to the device. You might be
able to use the scp command, for example.
• Replace device-ip-address with the IP of your device.
84
AWS IoT Greengrass Developer Guide, Version 2
Install with manual provisioning
scp -r greengrass-v2-certs/ device-ip-address:~
2. Create the Greengrass root folder on the device. You'll later install the AWS IoT Greengrass Core
software to this folder.
Linux or Unix
• Replace /greengrass/v2 with the folder to use.
sudo mkdir -p /greengrass/v2
Windows Command Prompt
• Replace C:\greengrass\v2 with the folder to use.
mkdir C:\greengrass\v2
PowerShell
• Replace C:\greengrass\v2 with the folder to use.
mkdir C:\greengrass\v2
3. (Linux only) Set the permissions of the parent of the Greengrass root folder.
• Replace /greengrass with the parent of the root folder.
sudo chmod 755 /greengrass
4. Copy the AWS IoT thing certificates to the Greengrass root folder.
Linux or Unix
• Replace /greengrass/v2 with the Greengrass root folder.
sudo cp -R ~/greengrass-v2-certs/* /greengrass/v2
Windows Command Prompt
• Replace C:\greengrass\v2 with the folder to use.
robocopy %USERPROFILE%\greengrass-v2-certs C:\greengrass\v2 /E
PowerShell
• Replace C:\greengrass\v2 with the folder to use.
85
AWS IoT Greengrass Developer Guide, Version 2
Install with manual provisioning
cp -Path ~\greengrass-v2-certs\* -Destination C:\greengrass\v2
5. Download the Amazon root certificate authority (CA) certificate. AWS IoT certificates are associated
with Amazon's root CA certificate by default.
Linux or Unix
sudo curl -o /greengrass/v2/AmazonRootCA1.pem https://www.amazontrust.com/
repository/AmazonRootCA1.pem
Windows Command Prompt (CMD)
curl -o C:\greengrass\v2\AmazonRootCA1.pem https://www.amazontrust.com/repository/
AmazonRootCA1.pem
PowerShell
iwr -Uri https://www.amazontrust.com/repository/AmazonRootCA1.pem -OutFile C:
\greengrass\v2\AmazonRootCA1.pem
Set up the device environment
Follow the steps in this section to set up a Linux or Windows device to use as your AWS IoT Greengrass
core device.
Set up a Linux device
To set up a Linux device for AWS IoT Greengrass V2
1. Install the Java runtime, which AWS IoT Greengrass Core software requires to run. We recommend
that you use Amazon Corretto 11 or OpenJDK 11.. The following commands show you how to install
OpenJDK on your device.
• For Debian-based or Ubuntu-based distributions:
sudo apt install default-jdk
• For Red Hat-based distributions:
sudo yum install java-11-openjdk-devel
When the installation completes, run the following command to verify that Java runs on your
Raspberry Pi.
java -version
The command prints the version of Java that runs on the device. For example, on a Debian-based
distribution, the output might look similar to the following sample.
openjdk version "11.0.9.1" 2020-11-04
OpenJDK Runtime Environment (build 11.0.9.1+1-post-Debian-1deb10u2)
86
AWS IoT Greengrass Developer Guide, Version 2
Install with manual provisioning
OpenJDK 64-Bit Server VM (build 11.0.9.1+1-post-Debian-1deb10u2, mixed mode)
2. (Optional) Create the default system user and group that runs components on your device. You can
also choose to let the AWS IoT Greengrass Core software installer create this user and group during
installation with the --component-default-user installer argument. For more information, see
Installer arguments (p. 126).
sudo adduser --system ggc_user
sudo addgroup --system ggc_group
3. Verify that the user that runs the AWS IoT Greengrass Core software (typically root), has permission
to run sudo with any user and any group.
a. Open the /etc/sudoers file.
b. Verify that the permission for the user looks like the following example.
root ALL=(ALL:ALL) ALL
4. Install all other required dependencies on your device as indicated by the list of requirements in
Device requirements (p. 63).
Set up a Windows device
Note
This feature is available for v2.5.0 and later of the Greengrass nucleus component (p. 181).
To set up a Windows device for AWS IoT Greengrass V2
1. Install the Java runtime, which AWS IoT Greengrass Core software requires to run. We recommend
that you use Amazon Corretto 11 or OpenJDK 11..
2. Open the Windows Command Prompt (cmd.exe) as an administrator.
3. Create the default user in the LocalSystem account on the Windows device. Replace password with
a secure password.
net user /add ggc_user password
4. Download and install the PsExec utility from Microsoft on the device.
5. Use the PsExec utility to store the user name and password for the default user in the Credential
Manager instance for the LocalSystem account. Replace password with the user's password that you
set earlier.
psexec -s cmd /c cmdkey /generic:ggc_user /user:ggc_user /pass:password
If the PsExec License Agreement opens, choose Accept to agree to the license and run the
command.
Note
On Windows devices, the LocalSystem account runs the Greengrass nucleus, and you must
use the PsExec utility to store the default user information in the LocalSystem account.
Using the Credential Manager application stores this information in the Windows account of
the currently logged on user, instead of the LocalSystem account.
Download the AWS IoT Greengrass Core software
You can download the latest version of the AWS IoT Greengrass Core software from the following
location:
87
AWS IoT Greengrass Developer Guide, Version 2
Install with manual provisioning
• https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip
Note
You can download a specific version of the AWS IoT Greengrass Core software from the
following location. Replace version with the version to download.
https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-version.zip
To download the AWS IoT Greengrass Core software
1. On your core device, download the AWS IoT Greengrass Core software to a file named
greengrass-nucleus-latest.zip.
Linux or Unix
curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-
latest.zip > greengrass-nucleus-latest.zip
Windows Command Prompt (CMD)
curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-
latest.zip > greengrass-nucleus-latest.zip
PowerShell
iwr -Uri https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-
latest.zip -OutFile greengrass-nucleus-latest.zip
By downloading this software, you agree to the Greengrass Core Software License Agreement.
2. Unzip the AWS IoT Greengrass Core software to a folder on your device. Replace
GreengrassInstaller with the folder that you want to use.
Linux or Unix
unzip greengrass-nucleus-latest.zip -d GreengrassInstaller && rm greengrass-
nucleus-latest.zip
Windows Command Prompt (CMD)
mkdir GreengrassInstaller && tar -xf greengrass-nucleus-latest.zip -
C GreengrassInstaller && del greengrass-nucleus-latest.zip
PowerShell
Expand-Archive -Path greengrass-nucleus-latest.zip -DestinationPath .
\GreengrassInstaller
rm greengrass-nucleus-latest.zip
3. (Optional) Run the following command to see the version of the AWS IoT Greengrass Core software.
java -jar ./GreengrassInstaller/lib/Greengrass.jar --version
88
AWS IoT Greengrass Developer Guide, Version 2
Install with manual provisioning
Important
If you install a version of the Greengrass nucleus earlier than v2.4.0, don't remove this folder
after you install the AWS IoT Greengrass Core software. The AWS IoT Greengrass Core software
uses the files in this folder to run.
If you downloaded the latest version of the software, you install v2.4.0 or later, and you can
remove this folder after you install the AWS IoT Greengrass Core software.
Install the AWS IoT Greengrass Core software
Run the installer with arguments that specify the following actions:
• Install from a partial configuration file that specifies to use the AWS resources and certificates that
you created earlier. The AWS IoT Greengrass Core software uses a configuration file that specifies
the configuration of every Greengrass component on the device. The installer creates a complete
configuration file from the partial configuration file that you provide.
• Specify to use the ggc_user system user to run software components on the core device. On Linux
devices, this command also specifies to use the ggc_group system group, and the installer creates the
system user and group for you.
• Set up the AWS IoT Greengrass Core software as a system service that runs as boot. On Linux devices,
this requires the Systemd init system.
For more information about the arguments that you can specify, see Installer arguments (p. 126).
Note
If you are running AWS IoT Greengrass on a device with limited memory, you can control the
amount of memory that AWS IoT Greengrass Core software uses. To control memory allocation,
you can set JVM heap size options in the jvmOptions configuration parameter in your nucleus
component. For more information, see Control memory allocation with JVM options (p. 160).
To install the AWS IoT Greengrass Core software
1. Check the version of the AWS IoT Greengrass Core software.
• Replace GreengrassInstaller with the path to the folder that contains the software.
java -jar ./GreengrassInstaller/lib/Greengrass.jar --version
2. Use a text editor to create a configuration file named config.yaml to provide to the installer.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano GreengrassInstaller/config.yaml
Copy the following YAML content into the file. This partial configuration file specifies system
parameters and Greengrass nucleus parameters.
---
system:
certificateFilePath: "/greengrass/v2/device.pem.crt"
privateKeyPath: "/greengrass/v2/private.pem.key"
rootCaPath: "/greengrass/v2/AmazonRootCA1.pem"
rootpath: "/greengrass/v2"
thingName: "MyGreengrassCore"
services:
89
AWS IoT Greengrass Developer Guide, Version 2
Install with manual provisioning
aws.greengrass.Nucleus:
componentType: "NUCLEUS"
version: "2.5.2"
configuration:
awsRegion: "us-west-2"
iotRoleAlias: "GreengrassCoreTokenExchangeRoleAlias"
iotDataEndpoint: "device-data-prefix-ats.iot.us-west-2.amazonaws.com"
iotCredEndpoint: "device-credentials-prefix.credentials.iot.us-
west-2.amazonaws.com"
Then, do the following:
• Replace each instance of /greengrass/v2 or C:\greengrass\v2 with the Greengrass root
folder.
• Replace MyGreengrassCore with the name of the AWS IoT thing.
• Replace 2.5.2 with the version of the AWS IoT Greengrass Core software.
• Replace us-west-2 with the AWS Region where you created the resources.
• Replace GreengrassCoreTokenExchangeRoleAlias with the name of the token exchange role
alias.
• Replace the iotDataEndpoint with your AWS IoT data endpoint.
• Replace the iotCredEndpoint with your AWS IoT credentials endpoint.
Note
In this configuration file, you can customize other nucleus configuration options such as the
ports and network proxy to use, as shown in the following example. For more information,
see Greengrass nucleus configuration (p. 182).
---
system:
certificateFilePath: "/greengrass/v2/device.pem.crt"
privateKeyPath: "/greengrass/v2/private.pem.key"
rootCaPath: "/greengrass/v2/AmazonRootCA1.pem"
rootpath: "/greengrass/v2"
thingName: "MyGreengrassCore"
services:
aws.greengrass.Nucleus:
componentType: "NUCLEUS"
version: "2.5.2"
configuration:
awsRegion: "us-west-2"
iotCredEndpoint: "device-credentials-prefix.credentials.iot.us-
west-2.amazonaws.com"
iotDataEndpoint: "device-data-prefix-ats.iot.us-west-2.amazonaws.com"
iotRoleAlias: "GreengrassCoreTokenExchangeRoleAlias"
mqtt:
port: 443
greengrassDataPlanePort: 443
networkProxy:
noProxyAddresses: "http://192.168.0.1,www.example.com"
proxy:
url: "https://my-proxy-server:1100"
username: "Mary_Major"
password: "pass@word1357"
3. Run the installer, and specify --init-config to provide the configuration file.
• Replace /greengrass/v2 or C:\greengrass\v2 with the Greengrass root folder.
• Replace each instance of GreengrassInstaller with the folder where you unpacked the
installer.
90
AWS IoT Greengrass Developer Guide, Version 2
Install with manual provisioning
Linux or Unix
sudo -E java -Droot="/greengrass/v2" -Dlog.store=FILE \
-jar ./GreengrassInstaller/lib/Greengrass.jar \
--init-config ./GreengrassInstaller/config.yaml \
--component-default-user ggc_user:ggc_group \
--setup-system-service true
Windows Command Prompt (CMD)
java -Droot="C:\greengrass\v2" "-Dlog.store=FILE" ^
-jar ./GreengrassInstaller/lib/Greengrass.jar ^
--init-config ./GreengrassInstaller/config.yaml ^
--component-default-user ggc_user ^
--setup-system-service true
PowerShell
java -Droot="C:\greengrass\v2" "-Dlog.store=FILE" `
-jar ./GreengrassInstaller/lib/Greengrass.jar `
--init-config ./GreengrassInstaller/config.yaml `
--component-default-user ggc_user `
--setup-system-service true
If you specify --setup-system-service true, the installer prints Successfully set up
Nucleus as a system service if it set up and ran the software as a system service. Otherwise,
the installer doesn't output any message if it installs the software successfully.
Note
You can't use the deploy-dev-tools argument to deploy local development tools when
you run the installer without the --provision true argument. For information about
deploying the Greengrass CLI directly on your device, see Greengrass Command Line
Interface (p. 428).
4. Verify the installation by viewing the files in the root folder.
Linux or Unix
ls /greengrass/v2
Windows Command Prompt (CMD)
dir C:\greengrass\v2
PowerShell
ls C:\greengrass\v2
If the installation succeeded, the root folder contains several folders, such as config, packages,
and logs.
91
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
If you installed the AWS IoT Greengrass Core software as a system service, the installer runs the software
for you. Otherwise, you must run the software manually. For more information, see Run the AWS IoT
Greengrass Core software (p. 128).
For more information about how to configure and use the software and AWS IoT Greengrass, see the
following:
• Configure the AWS IoT Greengrass Core software (p. 157)
• Develop AWS IoT Greengrass components (p. 440)
• Deploy AWS IoT Greengrass components to devices (p. 491)
• Greengrass Command Line Interface (p. 428)
Install AWS IoT Greengrass Core software with AWS
IoT fleet provisioning
This feature is available for v2.4.0 and later of the Greengrass nucleus component (p. 181).
With AWS IoT fleet provisioning, you can configure AWS IoT to generate and securely deliver X.509
device certificates and private keys to your devices when they connect to AWS IoT for the first time. AWS
IoT provides client certificates that are signed by the Amazon Root certificate authority (CA). You can
also configure AWS IoT to specify thing groups, thing types, and permissions for Greengrass core devices
that you provision with fleet provisioning. You define a provisioning template to define how AWS IoT
provisions each device. The provisioning template specifies the thing, policy, and certificate resources to
create for a device when provisioning. For more information, see Provisioning templates in the AWS IoT
Core Developer Guide.
AWS IoT Greengrass provides an AWS IoT fleet provisioning plugin that you can use to install the AWS
IoT Greengrass Core software using AWS resources created by AWS IoT fleet provisioning. The fleet
provisioning plugin uses provisioning by claim. Devices use a provisioning claim certificate and private key
to obtain a unique X.509 device certificate and private key that they can use for regular operations. You
can embed the claim certificate and private key in each device during manufacturing, so your customers
can activate devices later when each device comes online. You can use the same claim certificate and
private key for multiple devices. For more information, see Provisioning by claim in the AWS IoT Core
Developer Guide.
To install the AWS IoT Greengrass Core software with AWS IoT fleet provisioning, you must set up
resources in your AWS account that AWS IoT uses to provision Greengrass core devices. These resources
include a provisioning template, claim certificates, and a token exchange IAM role (p. 790). After
you create these resources, you can reuse them to provision multiple core devices in a fleet. For more
information, see Set up AWS IoT fleet provisioning for Greengrass core devices (p. 102).
Important
Before you download the AWS IoT Greengrass Core software, check that your core device meets
the requirements (p. 63) to install and run the AWS IoT Greengrass Core software v2.0.
Topics
• Prerequisites (p. 93)
• Retrieve AWS IoT endpoints (p. 80)
• Download certificates to the device (p. 93)
• Set up the device environment (p. 69)
• Download the AWS IoT Greengrass Core software (p. 72)
• Download the AWS IoT fleet provisioning plugin (p. 98)
• Install the AWS IoT Greengrass Core software (p. 98)
• Set up AWS IoT fleet provisioning for Greengrass core devices (p. 102)
92
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
• Configure the AWS IoT fleet provisioning plugin (p. 115)
Prerequisites
To install the AWS IoT Greengrass Core software with AWS IoT fleet provisioning, you must first set up
AWS IoT fleet provisioning for Greengrass core devices (p. 102). After you complete these steps once,
you can use fleet provisioning to install the AWS IoT Greengrass Core software on any number of devices.
Retrieve AWS IoT endpoints
Get the AWS IoT endpoints for your AWS account, and save them to use later. Your device uses these
endpoints to connect to AWS IoT. Do the following:
1. Get the AWS IoT data endpoint for your AWS account.
aws iot describe-endpoint --endpoint-type iot:Data-ATS
The response looks similar to the following example, if the request succeeds.
{
"endpointAddress": "device-data-prefix-ats.iot.us-west-2.amazonaws.com"
}
2. Get the AWS IoT credentials endpoint for your AWS account.
aws iot describe-endpoint --endpoint-type iot:CredentialProvider
The response looks similar to the following example, if the request succeeds.
{
"endpointAddress": "device-credentials-prefix.credentials.iot.us-
west-2.amazonaws.com"
}
Download certificates to the device
The device uses a claim certificate and private key to authenticate its request to provision AWS resources
and acquire an X.509 device certificate. You can embed the claim certificate and private key into the
device during manufacturing, or copy the certificate and key to the device during installation. In this
section, you copy the claim certificate and private key to the device. You also download the Amazon Root
certificate authority (CA) certificate to the device.
Important
Provisioning claim private keys should be secured at all times, including on Greengrass core
devices. We recommend that you use Amazon CloudWatch metrics and logs to monitor for
indications of misuse, such as unauthorized use of the claim certificate to provision devices. If
you detect misuse, disable the provisioning claim certificate so that it can't be used for device
provisioning. For more information, see Monitoring AWS IoT in the AWS IoT Core Developer
Guide.
To help you better manage the number of devices, and which devices, that register themselves
in your AWS account, you can specify a pre-provisioning hook when you create a fleet
provisioning template. A pre-provisioning hook is an AWS Lambda function that validates
template parameters that devices provide during registration. For example, you might create a
pre-provisioning hook that checks a device ID against a database to verify that the device has
93
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
permission to provision. For more information, see Pre-provisioning hooks in the AWS IoT Core
Developer Guide.
To download claim certificates to the device
1. Copy the claim certificate and private key to the device.
For example, you might run the scp command on your development computer to copy the claim
certificate and private key from a folder named claim-certs on your development computer to
the device.
• Replace device-ip-address with the IP address of your device.
scp -r claim-certs/ device-ip-address:~
2. Create the Greengrass root folder on the device. You'll later install the AWS IoT Greengrass Core
software to this folder.
Linux or Unix
• Replace /greengrass/v2 with the folder to use.
sudo mkdir -p /greengrass/v2
Windows Command Prompt
• Replace C:\greengrass\v2 with the folder to use.
mkdir C:\greengrass\v2
PowerShell
• Replace C:\greengrass\v2 with the folder to use.
mkdir C:\greengrass\v2
3. (Linux only) Set the permissions of the parent of the Greengrass root folder.
• Replace /greengrass with the parent of the root folder.
sudo chmod 755 /greengrass
4. Move the claim certificates to the Greengrass root folder.
• Replace /greengrass/v2 or C:\greengrass\v2 with the Greengrass root folder.
Linux or Unix
sudo mv ~/claim-certs /greengrass/v2
94
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
Windows Command Prompt (CMD)
move %USERPROFILE%\claim-certs C:\greengrass\v2
PowerShell
mv -Path ~\claim-certs -Destination C:\greengrass\v2
5. Download the Amazon root certificate authority (CA) certificate. AWS IoT certificates are associated
with Amazon's root CA certificate by default.
Linux or Unix
sudo curl -o /greengrass/v2/AmazonRootCA1.pem https://www.amazontrust.com/
repository/AmazonRootCA1.pem
Windows Command Prompt (CMD)
curl -o C:\greengrass\v2\AmazonRootCA1.pem https://www.amazontrust.com/repository/
AmazonRootCA1.pem
PowerShell
iwr -Uri https://www.amazontrust.com/repository/AmazonRootCA1.pem -OutFile C:
\greengrass\v2\AmazonRootCA1.pem
Set up the device environment
Follow the steps in this section to set up a Linux or Windows device to use as your AWS IoT Greengrass
core device.
Set up a Linux device
To set up a Linux device for AWS IoT Greengrass V2
1. Install the Java runtime, which AWS IoT Greengrass Core software requires to run. We recommend
that you use Amazon Corretto 11 or OpenJDK 11.. The following commands show you how to install
OpenJDK on your device.
• For Debian-based or Ubuntu-based distributions:
sudo apt install default-jdk
• For Red Hat-based distributions:
sudo yum install java-11-openjdk-devel
When the installation completes, run the following command to verify that Java runs on your
Raspberry Pi.
java -version
95
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
The command prints the version of Java that runs on the device. For example, on a Debian-based
distribution, the output might look similar to the following sample.
openjdk version "11.0.9.1" 2020-11-04
OpenJDK Runtime Environment (build 11.0.9.1+1-post-Debian-1deb10u2)
OpenJDK 64-Bit Server VM (build 11.0.9.1+1-post-Debian-1deb10u2, mixed mode)
2. (Optional) Create the default system user and group that runs components on your device. You can
also choose to let the AWS IoT Greengrass Core software installer create this user and group during
installation with the --component-default-user installer argument. For more information, see
Installer arguments (p. 126).
sudo adduser --system ggc_user
sudo addgroup --system ggc_group
3. Verify that the user that runs the AWS IoT Greengrass Core software (typically root), has permission
to run sudo with any user and any group.
a. Open the /etc/sudoers file.
b. Verify that the permission for the user looks like the following example.
root ALL=(ALL:ALL) ALL
4. Install all other required dependencies on your device as indicated by the list of requirements in
Device requirements (p. 63).
Set up a Windows device
Note
This feature is available for v2.5.0 and later of the Greengrass nucleus component (p. 181).
To set up a Windows device for AWS IoT Greengrass V2
1. Install the Java runtime, which AWS IoT Greengrass Core software requires to run. We recommend
that you use Amazon Corretto 11 or OpenJDK 11..
2. Open the Windows Command Prompt (cmd.exe) as an administrator.
3. Create the default user in the LocalSystem account on the Windows device. Replace password with
a secure password.
net user /add ggc_user password
4. Download and install the PsExec utility from Microsoft on the device.
5. Use the PsExec utility to store the user name and password for the default user in the Credential
Manager instance for the LocalSystem account. Replace password with the user's password that you
set earlier.
psexec -s cmd /c cmdkey /generic:ggc_user /user:ggc_user /pass:password
If the PsExec License Agreement opens, choose Accept to agree to the license and run the
command.
Note
On Windows devices, the LocalSystem account runs the Greengrass nucleus, and you must
use the PsExec utility to store the default user information in the LocalSystem account.
Using the Credential Manager application stores this information in the Windows account of
the currently logged on user, instead of the LocalSystem account.
96
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
Download the AWS IoT Greengrass Core software
You can download the latest version of the AWS IoT Greengrass Core software from the following
location:
• https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip
Note
You can download a specific version of the AWS IoT Greengrass Core software from the
following location. Replace version with the version to download.
https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-version.zip
To download the AWS IoT Greengrass Core software
1. On your core device, download the AWS IoT Greengrass Core software to a file named
greengrass-nucleus-latest.zip.
Linux or Unix
curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-
latest.zip > greengrass-nucleus-latest.zip
Windows Command Prompt (CMD)
curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-
latest.zip > greengrass-nucleus-latest.zip
PowerShell
iwr -Uri https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-
latest.zip -OutFile greengrass-nucleus-latest.zip
By downloading this software, you agree to the Greengrass Core Software License Agreement.
2. Unzip the AWS IoT Greengrass Core software to a folder on your device. Replace
GreengrassInstaller with the folder that you want to use.
Linux or Unix
unzip greengrass-nucleus-latest.zip -d GreengrassInstaller && rm greengrass-
nucleus-latest.zip
Windows Command Prompt (CMD)
mkdir GreengrassInstaller && tar -xf greengrass-nucleus-latest.zip -
C GreengrassInstaller && del greengrass-nucleus-latest.zip
PowerShell
Expand-Archive -Path greengrass-nucleus-latest.zip -DestinationPath .
\GreengrassInstaller
rm greengrass-nucleus-latest.zip
97
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
3. (Optional) Run the following command to see the version of the AWS IoT Greengrass Core software.
java -jar ./GreengrassInstaller/lib/Greengrass.jar --version
Important
If you install a version of the Greengrass nucleus earlier than v2.4.0, don't remove this folder
after you install the AWS IoT Greengrass Core software. The AWS IoT Greengrass Core software
uses the files in this folder to run.
If you downloaded the latest version of the software, you install v2.4.0 or later, and you can
remove this folder after you install the AWS IoT Greengrass Core software.
Download the AWS IoT fleet provisioning plugin
You can download the latest version of the AWS IoT fleet provisioning plugin from the following
location:
• https://d2s8p88vqu9w66.cloudfront.net/releases/aws-greengrass-FleetProvisioningByClaim/
fleetprovisioningbyclaim-latest.jar
To download the AWS IoT fleet provisioning plugin
• On your device, download the AWS IoT fleet provisioning plugin to a file named
aws.greengrass.FleetProvisioningByClaim.jar. Replace GreengrassInstaller with the
folder that you want to use.
Linux or Unix
curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/aws-greengrass-
FleetProvisioningByClaim/fleetprovisioningbyclaim-latest.jar > GreengrassInstaller/
aws.greengrass.FleetProvisioningByClaim.jar
Windows Command Prompt (CMD)
curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/aws-greengrass-
FleetProvisioningByClaim/fleetprovisioningbyclaim-latest.jar > GreengrassInstaller/
aws.greengrass.FleetProvisioningByClaim.jar
PowerShell
iwr -Uri https://d2s8p88vqu9w66.cloudfront.net/releases/aws-greengrass-
FleetProvisioningByClaim/fleetprovisioningbyclaim-latest.jar -
OutFile GreengrassInstaller/aws.greengrass.FleetProvisioningByClaim.jar
By downloading this software, you agree to the Greengrass Core Software License Agreement.
Install the AWS IoT Greengrass Core software
Run the installer with arguments that specify the following actions:
• Install from a partial configuration file that specifies to use the fleet provisioning plugin to provision
AWS resources. The AWS IoT Greengrass Core software uses a configuration file that specifies
the configuration of every Greengrass component on the device. The installer creates a complete
98
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
configuration file from the partial configuration file that you provide and the AWS resources that the
fleet provisioning plugin creates.
• Specify to use the ggc_user system user to run software components on the core device. On Linux
devices, this command also specifies to use the ggc_group system group, and the installer creates the
system user and group for you.
• Set up the AWS IoT Greengrass Core software as a system service that runs as boot. On Linux devices,
this requires the Systemd init system.
For more information about the arguments that you can specify, see Installer arguments (p. 126).
Note
If you are running AWS IoT Greengrass on a device with limited memory, you can control the
amount of memory that AWS IoT Greengrass Core software uses. To control memory allocation,
you can set JVM heap size options in the jvmOptions configuration parameter in your nucleus
component. For more information, see Control memory allocation with JVM options (p. 160).
To install the AWS IoT Greengrass Core software
1. Check the version of the AWS IoT Greengrass Core software.
• Replace GreengrassInstaller with the path to the folder that contains the software.
java -jar ./GreengrassInstaller/lib/Greengrass.jar --version
2. Use a text editor to create a configuration file named config.yaml to provide to the installer.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano GreengrassInstaller/config.yaml
Copy the following YAML content into the file. This partial configuration file specifies parameters
for the fleet provisioning plugin. For more information about the options that you can specify, see
Configure the AWS IoT fleet provisioning plugin (p. 115).
---
services:
aws.greengrass.Nucleus:
version: "2.5.2"
aws.greengrass.FleetProvisioningByClaim:
configuration:
rootPath: /greengrass/v2
awsRegion: "us-west-2"
iotDataEndpoint: "device-data-prefix-ats.iot.us-west-2.amazonaws.com"
iotCredentialEndpoint: "device-credentials-prefix.credentials.iot.us-
west-2.amazonaws.com"
iotRoleAlias: "GreengrassCoreTokenExchangeRoleAlias"
provisioningTemplate: "GreengrassFleetProvisioningTemplate"
claimCertificatePath: "/greengrass/v2/claim-certs/claim.pem.crt"
claimCertificatePrivateKeyPath: "/greengrass/v2/claim-certs/
claim.private.pem.key"
rootCaPath: "/greengrass/v2/AmazonRootCA1.pem"
templateParameters:
ThingName: "MyGreengrassCore"
ThingGroupName: "MyGreengrassCoreGroup"
Then, do the following:
99
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
• Replace 2.5.2 with the version of the AWS IoT Greengrass Core software.
• Replace each instance of /greengrass/v2 or C:\greengrass\v2 with the Greengrass root
folder.
• Replace us-west-2 with the AWS Region where you created the provisioning template and other
resources.
• Replace the iotDataEndpoint with your AWS IoT data endpoint.
• Replace the iotCredentialEndpoint with your AWS IoT credentials endpoint.
• Replace GreengrassCoreTokenExchangeRoleAlias with the name of the token exchange role
alias.
• Replace GreengrassFleetProvisioningTemplate with the name of the fleet provisioning
template.
• Replace the claimCertificatePath with the path to the claim certificate on the device.
• Replace the claimCertificatePrivateKeyPath with the path to the claim certificate private
key on the device.
• Replace the template parameters (templateParameters) with the values to use to provision
the device. This example refers to the example template (p. 110) that defines ThingName and
ThingGroupName parameters.
Note
In this configuration file, you can customize other configuration options such as the ports
and network proxy to use, as shown in the following example. For more information, see
Greengrass nucleus configuration (p. 182).
---
services:
aws.greengrass.Nucleus:
version: "2.5.2"
configuration:
mqtt:
port: 443
greengrassDataPlanePort: 443
networkProxy:
noProxyAddresses: "http://192.168.0.1,www.example.com"
proxy:
url: "http://my-proxy-server:1100"
username: "Mary_Major"
password: "pass@word1357"
aws.greengrass.FleetProvisioningByClaim:
configuration:
rootPath: /greengrass/v2
awsRegion: "us-west-2"
iotDataEndpoint: "device-data-prefix-ats.iot.us-west-2.amazonaws.com"
iotCredentialEndpoint: "device-credentials-prefix.credentials.iot.us-
west-2.amazonaws.com"
iotRoleAlias: "GreengrassCoreTokenExchangeRoleAlias"
provisioningTemplate: "GreengrassFleetProvisioningTemplate"
claimCertificatePath: "/greengrass/v2/claim-certs/claim.pem.crt"
claimCertificatePrivateKeyPath: "/greengrass/v2/claim-certs/
claim.private.pem.key"
rootCaPath: "/greengrass/v2/AmazonRootCA1.pem"
templateParameters:
ThingName: "MyGreengrassCore"
ThingGroupName: "MyGreengrassCoreGroup"
mqttPort: 443
proxyUrl: "http://my-proxy-server:1100"
proxyUserName: "Mary_Major"
proxyPassword: "pass@word1357"
100
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
3. Run the installer. Specify --trusted-plugin to provide the fleet provisioning plugin, and specify
--init-config to provide the configuration file.
• Replace /greengrass/v2 with the Greengrass root folder.
• Replace each instance of GreengrassInstaller with the folder where you unpacked the
installer.
Linux or Unix
sudo -E java -Droot="/greengrass/v2" -Dlog.store=FILE \
-jar ./GreengrassInstaller/lib/Greengrass.jar \
--trusted-plugin ./GreengrassInstaller/
aws.greengrass.FleetProvisioningByClaim.jar \
--init-config ./GreengrassInstaller/config.yaml \
--component-default-user ggc_user:ggc_group \
--setup-system-service true
Windows Command Prompt (CMD)
java -Droot="C:\greengrass\v2" "-Dlog.store=FILE" ^
-jar ./GreengrassInstaller/lib/Greengrass.jar ^
--trusted-plugin ./GreengrassInstaller/
aws.greengrass.FleetProvisioningByClaim.jar ^
--init-config ./GreengrassInstaller/config.yaml ^
--component-default-user ggc_user ^
--setup-system-service true
PowerShell
java -Droot="C:\greengrass\v2" "-Dlog.store=FILE" `
-jar ./GreengrassInstaller/lib/Greengrass.jar `
--trusted-plugin ./GreengrassInstaller/
aws.greengrass.FleetProvisioningByClaim.jar `
--init-config ./GreengrassInstaller/config.yaml `
--component-default-user ggc_user `
--setup-system-service true
If you specify --setup-system-service true, the installer prints Successfully set up
Nucleus as a system service if it set up and ran the software as a system service. Otherwise,
the installer doesn't output any message if it installs the software successfully.
Note
You can't use the deploy-dev-tools argument to deploy local development tools when
you run the installer without the --provision true argument. For information about
deploying the Greengrass CLI directly on your device, see Greengrass Command Line
Interface (p. 428).
4. Verify the installation by viewing the files in the root folder.
Linux or Unix
ls /greengrass/v2
Windows Command Prompt (CMD)
dir C:\greengrass\v2
101
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
PowerShell
ls C:\greengrass\v2
If the installation succeeded, the root folder contains several folders, such as config, packages,
and logs.
If you installed the AWS IoT Greengrass Core software as a system service, the installer runs the software
for you. Otherwise, you must run the software manually. For more information, see Run the AWS IoT
Greengrass Core software (p. 128).
For more information about how to configure and use the software and AWS IoT Greengrass, see the
following:
• Configure the AWS IoT Greengrass Core software (p. 157)
• Develop AWS IoT Greengrass components (p. 440)
• Deploy AWS IoT Greengrass components to devices (p. 491)
• Greengrass Command Line Interface (p. 428)
Set up AWS IoT fleet provisioning for Greengrass core devices
To install the AWS IoT Greengrass Core software with fleet provisioning (p. 92), you must first set
up the following resources in your AWS account. These resources enable devices to register themselves
with AWS IoT and operate as Greengrass core devices. Follow steps in this section once to create and
configure these resources in your AWS account.
• A token exchange IAM role, which core devices use to authorize calls to AWS services.
• An AWS IoT role alias that points to the token exchange role.
• (Optional) An AWS IoT policy, which core devices use to authorize calls to the AWS IoT and AWS
IoT Greengrass services. This AWS IoT policy must allow the iot:AssumeRoleWithCertificate
permission for the AWS IoT role alias that points to the token exchange role.
You can use a single AWS IoT policy for all core devices in your fleet, or you can configure your fleet
provisioning template to create an AWS IoT policy for each core device.
• An AWS IoT fleet provisioning template. This template must specify the following:
• An AWS IoT thing resource. You can specify a list of existing thing groups to deploy components to
each device when it comes online.
• An AWS IoT policy resource. This resource can define one of the following properties:
• The name of an existing AWS IoT policy. If you choose this option, the core devices that you create
from this template use the same AWS IoT policy, and you can manage their permissions as a fleet.
• An AWS IoT policy document. If you choose this option, each core device that you create from this
template uses a unique AWS IoT policy, and you can manage permissions for each individual core
device.
• An AWS IoT certificate resource. This certificate resource must use the
AWS::IoT::Certificate::Id parameter to attach the certificate to the core device. For more
information, see Just-in-time provisioning in the AWS IoT Developer Guide.
• An AWS IoT provisioning claim certificate and private key for the fleet provisioning template. You can
embed this certificate and private key in devices during manufacturing, so the devices can register and
provision themselves when they come online.
102
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
Important
Provisioning claim private keys should be secured at all times, including on Greengrass core
devices. We recommend that you use Amazon CloudWatch metrics and logs to monitor for
indications of misuse, such as unauthorized use of the claim certificate to provision devices. If
you detect misuse, disable the provisioning claim certificate so that it can't be used for device
provisioning. For more information, see Monitoring AWS IoT in the AWS IoT Core Developer
Guide.
To help you better manage the number of devices, and which devices, that register
themselves in your AWS account, you can specify a pre-provisioning hook when you create
a fleet provisioning template. A pre-provisioning hook is an AWS Lambda function that
validates template parameters that devices provide during registration. For example, you
might create a pre-provisioning hook that checks a device ID against a database to verify that
the device has permission to provision. For more information, see Pre-provisioning hooks in
the AWS IoT Core Developer Guide.
• An AWS IoT policy that you attach to the provisioning claim certificate to allow devices to register and
use the fleet provisioning template.
Topics
• Create a token exchange role (p. 80)
• Create an AWS IoT policy (p. 106)
• Create a fleet provisioning template (p. 108)
• Create a provisioning claim certificate and private key (p. 112)
Create a token exchange role
Greengrass core devices use an IAM service role, called the token exchange role, to authorize calls to AWS
services. The device uses the AWS IoT credentials provider to get temporary AWS credentials for this role,
which allows the device to interact with AWS IoT, send logs to Amazon CloudWatch Logs, and download
custom component artifacts from Amazon S3. For more information, see Authorize core devices to
interact with AWS services (p. 790).
You use an AWS IoT role alias to configure the token exchange role for Greengrass core devices. Role
aliases enable you to change the token exchange role for a device but keep the device configuration the
same. For more information, see Authorizing direct calls to AWS services in the AWS IoT Core Developer
Guide.
In this section, you create a token exchange IAM role and an AWS IoT role alias that points to the role.
If you have already set up a Greengrass core device, you can use its token exchange role and role alias
instead of creating new ones.
To create a token exchange IAM role
1. Create an IAM role that your device can use as a token exchange role. Do the following:
a. Create a file that contains the trust policy document that the token exchange role requires.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano device-role-trust-policy.json
Copy the following JSON into the file.
{
"Version": "2012-10-17",
103
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "credentials.iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
b. Create the token exchange role with the trust policy document.
• Replace GreengrassV2TokenExchangeRole with the name of the IAM role to create.
aws iam create-role --role-name GreengrassV2TokenExchangeRole --assume-role-policy-
document file://device-role-trust-policy.json
The response looks similar to the following example, if the request succeeds.
{
"Role": {
"Path": "/",
"RoleName": "GreengrassV2TokenExchangeRole",
"RoleId": "AROAZ2YMUHYHK5OKM77FB",
"Arn": "arn:aws:iam::123456789012:role/GreengrassV2TokenExchangeRole",
"CreateDate": "2021-02-06T00:13:29+00:00",
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "credentials.iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
}
c. Create a file that contains the access policy document that the token exchange role requires.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano device-role-access-policy.json
Copy the following JSON into the file.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:DescribeCertificate",
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
104
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
"logs:DescribeLogStreams",
"s3:GetBucketLocation"
],
"Resource": "*"
}
]
}
Note
This access policy doesn't allow access to component artifacts in S3 buckets. To deploy
custom components that define artifacts in Amazon S3, you must add permissions
to the role to allow your core device to retrieve component artifacts. For more
information, see Allow access to S3 buckets for component artifacts (p. 792).
If you don't yet have an S3 bucket for component artifacts, you can add these
permissions later after you create a bucket.
d. Create the IAM policy from the policy document.
• Replace GreengrassV2TokenExchangeRoleAccess with the name of the IAM policy to
create.
aws iam create-policy --policy-name GreengrassV2TokenExchangeRoleAccess --policy-
document file://device-role-access-policy.json
The response looks similar to the following example, if the request succeeds.
{
"Policy": {
"PolicyName": "GreengrassV2TokenExchangeRoleAccess",
"PolicyId": "ANPAZ2YMUHYHACI7C5Z66",
"Arn": "arn:aws:iam::123456789012:policy/GreengrassV2TokenExchangeRoleAccess",
"Path": "/",
"DefaultVersionId": "v1",
"AttachmentCount": 0,
"PermissionsBoundaryUsageCount": 0,
"IsAttachable": true,
"CreateDate": "2021-02-06T00:37:17+00:00",
"UpdateDate": "2021-02-06T00:37:17+00:00"
}
}
e. Attach the IAM policy to the token exchange role.
• Replace GreengrassV2TokenExchangeRole with the name of the IAM role.
• Replace the policy ARN with the ARN of the IAM policy that you created in the previous step.
aws iam attach-role-policy --role-name GreengrassV2TokenExchangeRole --policy-
arn arn:aws:iam::123456789012:policy/GreengrassV2TokenExchangeRoleAccess
The command doesn't have any output if the request succeeds.
2. Create an AWS IoT role alias that points to the token exchange role.
• Replace GreengrassCoreTokenExchangeRoleAlias with the name of the role alias to create.
• Replace the role ARN with the ARN of the IAM role that you created in the previous step.
105
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
aws iot create-role-alias --role-alias GreengrassCoreTokenExchangeRoleAlias --role-
arn arn:aws:iam::123456789012:role/GreengrassV2TokenExchangeRole
The response looks similar to the following example, if the request succeeds.
{
"roleAlias": "GreengrassCoreTokenExchangeRoleAlias",
"roleAliasArn": "arn:aws:iot:us-west-2:123456789012:rolealias/
GreengrassCoreTokenExchangeRoleAlias"
}
Note
To create a role alias, you must have permission to pass the token exchange IAM role to
AWS IoT. If you receive an error message when you try to create a role alias, check that your
AWS user has this permission. For more information, see Granting a user permissions to
pass a role to an AWS service in the AWS Identity and Access Management User Guide.
Create an AWS IoT policy
After you register a device as an AWS IoT thing, that device can use a digital certificate to authenticate
with AWS. This certificate includes one or more AWS IoT policies that define the permissions that a
device can use with the certificate. These policies allow the device to communicate with AWS IoT and
AWS IoT Greengrass.
With AWS IoT fleet provisioning, devices connect to AWS IoT to create and download a device certificate.
In the fleet provisioning template that you create in the next section, you can specify whether AWS IoT
attaches the same AWS IoT policy to all devices' certificates, or creates a new policy for each device.
In this section, you create an AWS IoT policy that AWS IoT attaches to all devices' certificates. With this
approach, you can manage permissions for all devices as a fleet. If you would rather create a new AWS
IoT policy for each device, you can skip this section, and refer to the policy in it when you define your
fleet template.
To create an AWS IoT policy
• Create an AWS IoT policy that defines the AWS IoT permissions for your fleet of Greengrass core
devices. The following policy allows access to all MQTT topics and Greengrass operations, so your
device works with custom applications and future changes that require new Greengrass operations.
This policy also allows the iot:AssumeRoleWithCertificate permission, which allows your
devices to use the token exchange role that you created in the previous section. You can restrict this
policy down based on your use case. For more information, see Minimal AWS IoT policy for AWS IoT
Greengrass V2 core devices (p. 777).
Do the following:
a. Create a file that contains the AWS IoT policy document that Greengrass core devices require.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano greengrass-v2-iot-policy.json
Copy the following JSON into the file.
106
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
• Replace the iot:AssumeRoleWithCertificate resource with the ARN of the AWS IoT role
alias that you created in the previous section.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish",
"iot:Subscribe",
"iot:Receive",
"iot:Connect",
"greengrass:*"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": "iot:AssumeRoleWithCertificate",
"Resource": "arn:aws:iot:us-west-2:123456789012:rolealias/
GreengrassCoreTokenExchangeRoleAlias"
}
]
}
b. Create an AWS IoT policy from the policy document.
• Replace GreengrassV2IoTThingPolicy with the name of the policy to create.
aws iot create-policy --policy-name GreengrassV2IoTThingPolicy --policy-document
file://greengrass-v2-iot-policy.json
The response looks similar to the following example, if the request succeeds.
{
"policyName": "GreengrassV2IoTThingPolicy",
"policyArn": "arn:aws:iot:us-west-2:123456789012:policy/
GreengrassV2IoTThingPolicy",
"policyDocument": "{
\"Version\": \"2012-10-17\",
\"Statement\": [
{
\"Effect\": \"Allow\",
\"Action\": [
\"iot:Publish\",
\"iot:Subscribe\",
\"iot:Receive\",
\"iot:Connect\",
\"greengrass:*\"
],
\"Resource\": [
\"*\"
]
},
{
\"Effect\": \"Allow\",
\"Action\": \"iot:AssumeRoleWithCertificate\",
107
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
\"Resource\": \"arn:aws:iot:us-west-2:123456789012:rolealias/
GreengrassCoreTokenExchangeRoleAlias\"
}
]
}",
"policyVersionId": "1"
}
Create a fleet provisioning template
AWS IoT fleet provisioning templates define how to provision AWS IoT things, policies, and certificates.
To provision Greengrass core devices with the fleet provisioning plugin, you must create a template that
specifies that following:
• An AWS IoT thing resource. You can specify a list of existing thing groups to deploy components to
each device when it comes online.
• An AWS IoT policy resource. This resource can define one of the following properties:
• The name of an existing AWS IoT policy. If you choose this option, the core devices that you create
from this template use the same AWS IoT policy, and you can manage their permissions as a fleet.
• An AWS IoT policy document. If you choose this option, each core device that you create from this
template uses a unique AWS IoT policy, and you can manage permissions for each individual core
device.
• An AWS IoT certificate resource. This certificate resource must use the
AWS::IoT::Certificate::Id parameter to attach the certificate to the core device. For more
information, see Just-in-time provisioning in the AWS IoT Developer Guide.
In the template, you can specify to add the AWS IoT thing to a list of existing thing groups. When the
core device connects to AWS IoT Greengrass for the first time, it receives Greengrass deployments for
each thing group where it's a member. You can use thing groups to deploy the latest software to each
device as soon as it comes online. For more information, see Deploy AWS IoT Greengrass components to
devices (p. 491).
The AWS IoT service requires permissions to create and update AWS IoT resources in your AWS account
when provisioning devices. To give the AWS IoT service access, you create an IAM role and provide it
when you create the template. AWS IoT provides an managed policy, AWSIoTThingsRegistration, that
allows access to all permissions that AWS IoT might use when provisioning devices. You can use this
managed policy, or create a custom policy that scopes down the permissions in the managed policy for
your use case.
In this section, you create an IAM role that allows AWS IoT to provision resources for devices, and you
create a fleet provisioning template that uses that IAM role.
To create a fleet provisioning template
1. Create an IAM role that AWS IoT can assume to provision resources in your AWS account. Do the
following:
a. Create a file that contains the trust policy document that allows AWS IoT to assume the role.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano aws-iot-trust-policy.json
Copy the following JSON into the file.
108
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
b. Create an IAM role with the trust policy document.
• Replace GreengrassFleetProvisioningRole with the name of the IAM role to create.
aws iam create-role --role-name GreengrassFleetProvisioningRole --assume-role-
policy-document file://aws-iot-trust-policy.json
The response looks similar to the following example, if the request succeeds.
{
"Role": {
"Path": "/",
"RoleName": "GreengrassFleetProvisioningRole",
"RoleId": "AROAZ2YMUHYHK5OKM77FB",
"Arn": "arn:aws:iam::123456789012:role/GreengrassFleetProvisioningRole",
"CreateDate": "2021-07-26T00:15:12+00:00",
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
}
}
c. Review the AWSIoTThingsRegistration policy, which allows access to all permissions that AWS
IoT might use when provisioning devices. You can use this managed policy, or create a custom
policy that defines scoped-down permissions for your use case. If you choose to create a custom
policy, do so now.
d. Attach the IAM policy to the fleet provisioning role.
• Replace GreengrassFleetProvisioningRole with the name of the IAM role.
• If you created a custom policy in the previous step, replace the policy ARN with the ARN of
the IAM policy to use.
aws iam attach-role-policy --role-name GreengrassFleetProvisioningRole --policy-
arn arn:aws:iam::aws:policy/service-role/AWSIoTThingsRegistration
109
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
The command doesn't have any output if the request succeeds.
2. (Optional) Create a pre-provisioning hook, which is an AWS Lambda function that validates template
parameters that devices provide during registration. You can use a pre-provisioning hook to
gain more control over which and how many devices onboard in your AWS account. For more
information, see Pre-provisioning hooks in the AWS IoT Core Developer Guide.
3. Create a fleet provisioning template. Do the following:
a. Create a file to contain the provisioning template document.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano greengrass-fleet-provisioning-template.json
Write the provisioning template document. You can start from the following example
provisioning template, which specifies to create an AWS IoT thing with the following properties:
• The thing's name is the value that you specify in the ThingName template parameter.
• The thing is a member of the thing group that you specify in the ThingGroupName template
parameter. The thing group must exist in your AWS account.
• The thing's certificate has the AWS IoT policy named GreengrassV2IoTThingPolicy
attached to it.
For more information, see Provisioning templates in the AWS IoT Core Developer Guide.
{
"Parameters": {
"ThingName": {
"Type": "String"
},
"ThingGroupName": {
"Type": "String"
},
"AWS::IoT::Certificate::Id": {
"Type": "String"
}
},
"Resources": {
"MyThing": {
"OverrideSettings": {
"AttributePayload": "REPLACE",
"ThingGroups": "REPLACE",
"ThingTypeName": "REPLACE"
},
"Properties": {
"AttributePayload": {},
"ThingGroups": [
{
"Ref": "ThingGroupName"
}
],
"ThingName": {
"Ref": "ThingName"
}
},
"Type": "AWS::IoT::Thing"
},
"MyPolicy": {
110
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
"Properties": {
"PolicyName": "GreengrassV2IoTThingPolicy"
},
"Type": "AWS::IoT::Policy"
},
"MyCertificate": {
"Properties": {
"CertificateId": {
"Ref": "AWS::IoT::Certificate::Id"
},
"Status": "Active"
},
"Type": "AWS::IoT::Certificate"
}
}
}
Note
MyThing, MyPolicy, and MyCertificate are arbitrary names that identify each
resource specification in the fleet provisioning template. AWS IoT doesn't use these
names in the resources that it creates from the template. You can use these names or
replace them with values that help you identify each resource in the template.
b. Create the fleet provisioning template from the provisioning template document.
• Replace GreengrassFleetProvisioningTemplate with the name of the template to
create.
• Replace the template description with a description for your template.
• Replace the provisioning role ARN with the ARN of the role that you created earlier.
Linux or Unix
aws iot create-provisioning-template \
--template-name GreengrassFleetProvisioningTemplate \
--description "A provisioning template for Greengrass core devices." \
--provisioning-role-arn "arn:aws:iam::123456789012:role/
GreengrassFleetProvisioningRole" \
--template-body file://greengrass-fleet-provisioning-template.json \
--enabled
Windows Command Prompt (CMD)
aws iot create-provisioning-template ^
--template-name GreengrassFleetProvisioningTemplate ^
--description "A provisioning template for Greengrass core devices." ^
--provisioning-role-arn "arn:aws:iam::123456789012:role/
GreengrassFleetProvisioningRole" ^
--template-body file://greengrass-fleet-provisioning-template.json ^
--enabled
PowerShell
aws iot create-provisioning-template `
--template-name GreengrassFleetProvisioningTemplate `
--description "A provisioning template for Greengrass core devices." `
--provisioning-role-arn "arn:aws:iam::123456789012:role/
GreengrassFleetProvisioningRole" `
--template-body file://greengrass-fleet-provisioning-template.json `
--enabled
111
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
Note
If you created a pre-provisioning hook, specify the ARN of the pre-provisioning hook's
Lambda function with the --pre-provisioning-hook argument.
--pre-provisioning-hook targetArn=arn:aws:lambda:us-
west-2:123456789012:function:GreengrassPreProvisioningHook
The response looks similar to the following example, if the request succeeds.
{
"templateArn": "arn:aws:iot:us-west-2:123456789012:provisioningtemplate/
GreengrassFleetProvisioningTemplate",
"templateName": "GreengrassFleetProvisioningTemplate",
"defaultVersionId": 1
}
Create a provisioning claim certificate and private key
Claim certificates are X.509 certificates that allow devices to register as AWS IoT things and retrieve a
unique X.509 device certificate to use for regular operations. After you create a claim certificate, you
attach an AWS IoT policy that allows devices to use it to create unique device certificates and provision
with a fleet provisioning template. Devices with the claim certificate can provision using only the
provisioning template that you allow in the AWS IoT policy.
In this section, you create the claim certificate and configure it for devices to use with the fleet
provisioning template that you created in the previous section.
Important
Provisioning claim private keys should be secured at all times, including on Greengrass core
devices. We recommend that you use Amazon CloudWatch metrics and logs to monitor for
indications of misuse, such as unauthorized use of the claim certificate to provision devices. If
you detect misuse, disable the provisioning claim certificate so that it can't be used for device
provisioning. For more information, see Monitoring AWS IoT in the AWS IoT Core Developer
Guide.
To help you better manage the number of devices, and which devices, that register themselves
in your AWS account, you can specify a pre-provisioning hook when you create a fleet
provisioning template. A pre-provisioning hook is an AWS Lambda function that validates
template parameters that devices provide during registration. For example, you might create a
pre-provisioning hook that checks a device ID against a database to verify that the device has
permission to provision. For more information, see Pre-provisioning hooks in the AWS IoT Core
Developer Guide.
To create a provisioning claim certificate and private key
1. Create a folder where you download the claim certificate and private key.
mkdir claim-certs
2. Create and save a certificate and private key to use for provisioning. AWS IoT provides client
certificates that are signed by the Amazon Root certificate authority (CA).
Linux or Unix
aws iot create-keys-and-certificate \
--certificate-pem-outfile "claim-certs/claim.pem.crt" \
112
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
--public-key-outfile "claim-certs/claim.public.pem.key" \
--private-key-outfile "claim-certs/claim.private.pem.key" \
--set-as-active
Windows Command Prompt (CMD)
aws iot create-keys-and-certificate ^
--certificate-pem-outfile "claim-certs/claim.pem.crt" ^
--public-key-outfile "claim-certs/claim.public.pem.key" ^
--private-key-outfile "claim-certs/claim.private.pem.key" ^
--set-as-active
PowerShell
aws iot create-keys-and-certificate `
--certificate-pem-outfile "claim-certs/claim.pem.crt" `
--public-key-outfile "claim-certs/claim.public.pem.key" `
--private-key-outfile "claim-certs/claim.private.pem.key" `
--set-as-active
The response contains information about the certificate, if the request succeeds. Save the
certificate's ARN to use later.
3. Create and attach an AWS IoT policy that allows devices to use the certificate to create unique device
certificates and provision with the fleet provisioning template. The following policy allows access to
the device provisioning MQTT API. For more information, see Device provisioning MQTT API in the
AWS IoT Core Developer Guide.
Do the following:
a. Create a file that contains the AWS IoT policy document that Greengrass core devices require.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano greengrass-provisioning-claim-iot-policy.json
Copy the following JSON into the file.
• Replace each instance of region with the AWS Region where you set up fleet provisioning.
• Replace each instance of account-id with your AWS account ID.
• Replace each instance of GreengrassFleetProvisioningTemplate with the name of the
fleet provisioning template that you created in the previous section.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:Connect",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"iot:Publish",
"iot:Receive"
113
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
],
"Resource": [
"arn:aws:iot:region:account-id:topic/$aws/certificates/create/*",
"arn:aws:iot:region:account-id:topic/$aws/provisioning-
templates/GreengrassFleetProvisioningTemplate/provision/*"
]
},
{
"Effect": "Allow",
"Action": "iot:Subscribe",
"Resource": [
"arn:aws:iot:region:account-id:topicfilter/$aws/certificates/create/*",
"arn:aws:iot:region:account-id:topicfilter/$aws/provisioning-
templates/GreengrassFleetProvisioningTemplate/provision/*"
]
}
]
}
b. Create an AWS IoT policy from the policy document.
• Replace GreengrassProvisioningClaimPolicy with the name of the policy to create.
aws iot create-policy --policy-name GreengrassProvisioningClaimPolicy --policy-
document file://greengrass-provisioning-claim-iot-policy.json
The response looks similar to the following example, if the request succeeds.
{
"policyName": "GreengrassProvisioningClaimPolicy",
"policyArn": "arn:aws:iot:us-west-2:123456789012:policy/
GreengrassProvisioningClaimPolicy",
"policyDocument": "{
\"Version\": \"2012-10-17\",
\"Statement\": [
{
\"Effect\": \"Allow\",
\"Action\": \"iot:Connect\",
\"Resource\": \"*\"
},
{
\"Effect\": \"Allow\",
\"Action\": [
\"iot:Publish\",
\"iot:Receive\"
],
\"Resource\": [
\"arn:aws:iot:region:account-id:topic/$aws/certificates/create/*\",
\"arn:aws:iot:region:account-id:topic/$aws/provisioning-
templates/GreengrassFleetProvisioningTemplate/provision/*\"
]
},
{
\"Effect\": \"Allow\",
\"Action\": \"iot:Subscribe\",
\"Resource\": [
\"arn:aws:iot:region:account-id:topicfilter/$aws/certificates/create/*\",
\"arn:aws:iot:region:account-id:topicfilter/$aws/provisioning-
templates/GreengrassFleetProvisioningTemplate/provision/*\"
]
}
]
114
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
}",
"policyVersionId": "1"
}
4. Attach the AWS IoT policy to the provisioning claim certificate.
• Replace GreengrassProvisioningClaimPolicy with the name of the policy to attach.
• Replace the target ARN with the ARN of the provisioning claim certificate.
aws iot attach-policy --policy-name GreengrassProvisioningClaimPolicy
--target arn:aws:iot:us-west-2:123456789012:cert/
aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4
The command doesn't have any output if the request succeeds.
You now have a provisioning claim certificate and private key that devices can use to register with AWS
IoT and provision themselves as Greengrass core devices. You can embed the claim certificate and private
key in devices during manufacturing, or copy the certificate and key to devices before you install the
AWS IoT Greengrass Core software. For more information, see Install AWS IoT Greengrass Core software
with AWS IoT fleet provisioning (p. 92).
Configure the AWS IoT fleet provisioning plugin
The AWS IoT fleet provisioning plugin provides the following configuration parameters that you can
customize when you install the AWS IoT Greengrass Core software with fleet provisioning (p. 92).
rootPath
The path to the folder to use as the root for the AWS IoT Greengrass Core software.
awsRegion
The AWS Region that the fleet provisioning plugin uses to provision AWS resources.
iotDataEndpoint
The AWS IoT data endpoint for your AWS account.
iotCredentialEndpoint
The AWS IoT credentials endpoint for your AWS account.
iotRoleAlias
The AWS IoT role alias that points to a token exchange IAM role. The AWS IoT credentials provider
assumes this role to allow the Greengrass core device to interact with AWS services. For more
information, see Authorize core devices to interact with AWS services (p. 790).
provisioningTemplate
The AWS IoT fleet provisioning template to use to provision AWS resources. This template must
specify the following:
• An AWS IoT thing resource. You can specify a list of existing thing groups to deploy components to
each device when it comes online.
• An AWS IoT policy resource. This resource can define one of the following properties:
• The name of an existing AWS IoT policy. If you choose this option, the core devices that you
create from this template use the same AWS IoT policy, and you can manage their permissions
as a fleet.
115
AWS IoT Greengrass Developer Guide, Version 2
Install with fleet provisioning
• An AWS IoT policy document. If you choose this option, each core device that you create from
this template uses a unique AWS IoT policy, and you can manage permissions for each individual
core device.
• An AWS IoT certificate resource. This certificate resource must use the
AWS::IoT::Certificate::Id parameter to attach the certificate to the core device. For more
information, see Just-in-time provisioning in the AWS IoT Developer Guide.
For more information, see Provisioning templates in the AWS IoT Core Developer Guide.
claimCertificatePath
The path to the provisioning claim certificate for the provisioning template that you specify in
provisioningTemplate. For more information, see CreateProvisioningClaim in the AWS IoT Core
API Reference.
claimCertificatePrivateKeyPath
The path to the provisioning claim certificate private key for the provisioning template that you
specify in provisioningTemplate. For more information, see CreateProvisioningClaim in the AWS
IoT Core API Reference.
Important
Provisioning claim private keys should be secured at all times, including on Greengrass core
devices. We recommend that you use Amazon CloudWatch metrics and logs to monitor for
indications of misuse, such as unauthorized use of the claim certificate to provision devices.
If you detect misuse, disable the provisioning claim certificate so that it can't be used for
device provisioning. For more information, see Monitoring AWS IoT in the AWS IoT Core
Developer Guide.
To help you better manage the number of devices, and which devices, that register
themselves in your AWS account, you can specify a pre-provisioning hook when you create
a fleet provisioning template. A pre-provisioning hook is an AWS Lambda function that
validates template parameters that devices provide during registration. For example, you
might create a pre-provisioning hook that checks a device ID against a database to verify
that the device has permission to provision. For more information, see Pre-provisioning
hooks in the AWS IoT Core Developer Guide.
rootCaPath
The path to the Amazon root certificate authority (CA) certificate.
templateParameters
(Optional) The map of parameters to provide to the fleet provisioning template. For more
information, see Provisioning templates' parameters section in the AWS IoT Core Developer Guide.
deviceId
(Optional) The device identifier to use as the client ID when the fleet provisioning plugin creates an
MQTT connection to AWS IoT.
Default: A random UUID.
mqttPort
(Optional) The port to use for MQTT connections.
Default: 8883
proxyUrl
(Optional) The URL of the proxy server in the format scheme://userinfo@host:port.
• scheme – The scheme, which must be http or https.
Important
Greengrass core devices must run Greengrass nucleus (p. 181) v2.5.0 or later to use
HTTPS proxies.
116
AWS IoT Greengrass Developer Guide, Version 2
Install with custom provisioning
If you configure an HTTPS proxy, you must add the proxy server CA certificate to the core
device's Amazon root CA certificate. For more information, see Enable the core device to
trust an HTTPS proxy (p. 168).
• userinfo – (Optional) The user name and password information. If you specify this information
in the url, the Greengrass core device ignores the username and password fields.
• host – The host name or IP address of the proxy server.
• port – (Optional) The port number. If you don't specify the port, then the Greengrass core device
uses the following default values:
• http – 80
• https – 443
proxyUserName
(Optional) The user name that authenticates the proxy server.
proxyPassword
(Optional) The user name that authenticates the proxy server.
Install AWS IoT Greengrass Core software with
custom resource provisioning
This feature is available for v2.4.0 and later of the Greengrass nucleus component (p. 181).
The AWS IoT Greengrass Core software installer provides a Java interface that you can implement
in a custom plugin that provisions required AWS resources. You can develop a provisioning plugin
to use custom X.509 client certificates or to run complex provisioning steps that other installation
processes don't support. For more information, see Create your own client certificates in the AWS IoT
Core Developer Guide.
To run a custom provisioning plugin when you install the AWS IoT Greengrass Core software, you
create a JAR file that you provide to the installer. The installer runs the plugin, and the plugin returns a
provisioning configuration that defines the AWS resources for the Greengrass core device. The installer
uses this information to configure the AWS IoT Greengrass Core software on the device. For more
information, see Develop custom provisioning plugins (p. 124).
Important
Before you download the AWS IoT Greengrass Core software, check that your core device meets
the requirements (p. 63) to install and run the AWS IoT Greengrass Core software v2.0.
Topics
• Prerequisites (p. 117)
• Set up the device environment (p. 69)
• Download the AWS IoT Greengrass Core software (p. 72)
• Install the AWS IoT Greengrass Core software (p. 120)
• Develop custom provisioning plugins (p. 124)
Prerequisites
To install the AWS IoT Greengrass Core software with custom provisioning, you must have the following:
• A JAR file for a custom provisioning plugin that implements the DeviceIdentityInterface. The
custom provisioning plugin must return values for each system and nucleus configuration parameter.
117
AWS IoT Greengrass Developer Guide, Version 2
Install with custom provisioning
Otherwise, you must provide those values in the configuration file during installation. For more
information, see Develop custom provisioning plugins (p. 124).
Set up the device environment
Follow the steps in this section to set up a Linux or Windows device to use as your AWS IoT Greengrass
core device.
Set up a Linux device
To set up a Linux device for AWS IoT Greengrass V2
1. Install the Java runtime, which AWS IoT Greengrass Core software requires to run. We recommend
that you use Amazon Corretto 11 or OpenJDK 11.. The following commands show you how to install
OpenJDK on your device.
• For Debian-based or Ubuntu-based distributions:
sudo apt install default-jdk
• For Red Hat-based distributions:
sudo yum install java-11-openjdk-devel
When the installation completes, run the following command to verify that Java runs on your
Raspberry Pi.
java -version
The command prints the version of Java that runs on the device. For example, on a Debian-based
distribution, the output might look similar to the following sample.
openjdk version "11.0.9.1" 2020-11-04
OpenJDK Runtime Environment (build 11.0.9.1+1-post-Debian-1deb10u2)
OpenJDK 64-Bit Server VM (build 11.0.9.1+1-post-Debian-1deb10u2, mixed mode)
2. (Optional) Create the default system user and group that runs components on your device. You can
also choose to let the AWS IoT Greengrass Core software installer create this user and group during
installation with the --component-default-user installer argument. For more information, see
Installer arguments (p. 126).
sudo adduser --system ggc_user
sudo addgroup --system ggc_group
3. Verify that the user that runs the AWS IoT Greengrass Core software (typically root), has permission
to run sudo with any user and any group.
a. Open the /etc/sudoers file.
b. Verify that the permission for the user looks like the following example.
root ALL=(ALL:ALL) ALL
4. Install all other required dependencies on your device as indicated by the list of requirements in
Device requirements (p. 63).
118
AWS IoT Greengrass Developer Guide, Version 2
Install with custom provisioning
Set up a Windows device
Note
This feature is available for v2.5.0 and later of the Greengrass nucleus component (p. 181).
To set up a Windows device for AWS IoT Greengrass V2
1. Install the Java runtime, which AWS IoT Greengrass Core software requires to run. We recommend
that you use Amazon Corretto 11 or OpenJDK 11..
2. Open the Windows Command Prompt (cmd.exe) as an administrator.
3. Create the default user in the LocalSystem account on the Windows device. Replace password with
a secure password.
net user /add ggc_user password
4. Download and install the PsExec utility from Microsoft on the device.
5. Use the PsExec utility to store the user name and password for the default user in the Credential
Manager instance for the LocalSystem account. Replace password with the user's password that you
set earlier.
psexec -s cmd /c cmdkey /generic:ggc_user /user:ggc_user /pass:password
If the PsExec License Agreement opens, choose Accept to agree to the license and run the
command.
Note
On Windows devices, the LocalSystem account runs the Greengrass nucleus, and you must
use the PsExec utility to store the default user information in the LocalSystem account.
Using the Credential Manager application stores this information in the Windows account of
the currently logged on user, instead of the LocalSystem account.
Download the AWS IoT Greengrass Core software
You can download the latest version of the AWS IoT Greengrass Core software from the following
location:
• https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip
Note
You can download a specific version of the AWS IoT Greengrass Core software from the
following location. Replace version with the version to download.
https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-version.zip
To download the AWS IoT Greengrass Core software
1. On your core device, download the AWS IoT Greengrass Core software to a file named
greengrass-nucleus-latest.zip.
Linux or Unix
curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-
latest.zip > greengrass-nucleus-latest.zip
119
AWS IoT Greengrass Developer Guide, Version 2
Install with custom provisioning
Windows Command Prompt (CMD)
curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-
latest.zip > greengrass-nucleus-latest.zip
PowerShell
iwr -Uri https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-
latest.zip -OutFile greengrass-nucleus-latest.zip
By downloading this software, you agree to the Greengrass Core Software License Agreement.
2. Unzip the AWS IoT Greengrass Core software to a folder on your device. Replace
GreengrassInstaller with the folder that you want to use.
Linux or Unix
unzip greengrass-nucleus-latest.zip -d GreengrassInstaller && rm greengrass-
nucleus-latest.zip
Windows Command Prompt (CMD)
mkdir GreengrassInstaller && tar -xf greengrass-nucleus-latest.zip -
C GreengrassInstaller && del greengrass-nucleus-latest.zip
PowerShell
Expand-Archive -Path greengrass-nucleus-latest.zip -DestinationPath .
\GreengrassInstaller
rm greengrass-nucleus-latest.zip
3. (Optional) Run the following command to see the version of the AWS IoT Greengrass Core software.
java -jar ./GreengrassInstaller/lib/Greengrass.jar --version
Important
If you install a version of the Greengrass nucleus earlier than v2.4.0, don't remove this folder
after you install the AWS IoT Greengrass Core software. The AWS IoT Greengrass Core software
uses the files in this folder to run.
If you downloaded the latest version of the software, you install v2.4.0 or later, and you can
remove this folder after you install the AWS IoT Greengrass Core software.
Install the AWS IoT Greengrass Core software
Run the installer with arguments that specify the following actions:
• Install from a partial configuration file that specifies to use your custom provisioning plugin to
provision AWS resources. The AWS IoT Greengrass Core software uses a configuration file that specifies
the configuration of every Greengrass component on the device. The installer creates a complete
configuration file from the partial configuration file that you provide and the AWS resources that the
custom provisioning plugin creates.
120
AWS IoT Greengrass Developer Guide, Version 2
Install with custom provisioning
• Specify to use the ggc_user system user to run software components on the core device. On Linux
devices, this command also specifies to use the ggc_group system group, and the installer creates the
system user and group for you.
• Set up the AWS IoT Greengrass Core software as a system service that runs as boot. On Linux devices,
this requires the Systemd init system.
For more information about the arguments that you can specify, see Installer arguments (p. 126).
Note
If you are running AWS IoT Greengrass on a device with limited memory, you can control the
amount of memory that AWS IoT Greengrass Core software uses. To control memory allocation,
you can set JVM heap size options in the jvmOptions configuration parameter in your nucleus
component. For more information, see Control memory allocation with JVM options (p. 160).
To install the AWS IoT Greengrass Core software (Linux)
1. Check the version of the AWS IoT Greengrass Core software.
• Replace GreengrassInstaller with the path to the folder that contains the software.
java -jar ./GreengrassInstaller/lib/Greengrass.jar --version
2. Use a text editor to create a configuration file named config.yaml to provide to the installer.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano GreengrassInstaller/config.yaml
Copy the following YAML content into the file.
---
system:
rootpath: "/greengrass/v2"
# The following values are optional. Return them from the provisioning plugin or set
them here.
# certificateFilePath: ""
# privateKeyPath: ""
# rootCaPath: ""
# thingName: ""
services:
aws.greengrass.Nucleus:
version: "2.5.2"
configuration:
# The following values are optional. Return them from the provisioning plugin or
set them here.
# awsRegion: ""
# iotRoleAlias: ""
# iotDataEndpoint: ""
# iotCredEndpoint: ""
com.example.CustomProvisioning:
configuration:
# You can specify configuration parameters to provide to your plugin.
# pluginParameter: ""
Then, do the following:
• Replace 2.5.2 with the version of the AWS IoT Greengrass Core software.
121
AWS IoT Greengrass Developer Guide, Version 2
Install with custom provisioning
• Replace each instance of /greengrass/v2 with the Greengrass root folder.
• (Optional) Specify system and nucleus configuration values. You must set these values if your
provisioning plugin doesn't provide them.
• (Optional) Specify configuration parameters to provide to your provisioning plugin.
Note
In this configuration file, you can customize other configuration options, such as the ports
and network proxy to use, as shown in the following example. For more information, see
Greengrass nucleus configuration (p. 182).
---
system:
rootpath: "/greengrass/v2"
# The following values are optional. Return them from the provisioning plugin
or set them here.
# certificateFilePath: ""
# privateKeyPath: ""
# rootCaPath: ""
# thingName: ""
services:
aws.greengrass.Nucleus:
version: "2.5.2"
configuration:
mqtt:
port: 443
greengrassDataPlanePort: 443
networkProxy:
noProxyAddresses: "http://192.168.0.1,www.example.com"
proxy:
url: "http://my-proxy-server:1100"
username: "Mary_Major"
password: "pass@word1357"
# The following values are optional. Return them from the provisioning
plugin or set them here.
# awsRegion: ""
# iotRoleAlias: ""
# iotDataEndpoint: ""
# iotCredEndpoint: ""
com.example.CustomProvisioning:
configuration:
# You can specify configuration parameters to provide to your plugin.
# pluginParameter: ""
3. Run the installer. Specify --trusted-plugin to provide your custom provisioning plugin, and
specify --init-config to provide the configuration file.
• Replace /greengrass/v2 or C:\greengrass\v2 with the Greengrass root folder.
• Replace each instance of GreengrassInstaller with the folder where you unpacked the
installer.
• Replace the path to the custom provisioning plugin JAR file with the path to your plugin's JAR file.
Linux or Unix
sudo -E java -Droot="/greengrass/v2" -Dlog.store=FILE \
-jar ./GreengrassInstaller/lib/Greengrass.jar \
--trusted-plugin /path/to/com.example.CustomProvisioning.jar \
--init-config ./GreengrassInstaller/config.yaml \
--component-default-user ggc_user:ggc_group \
122
AWS IoT Greengrass Developer Guide, Version 2
Install with custom provisioning
--setup-system-service true
Windows Command Prompt (CMD)
java -Droot="C:\greengrass\v2" "-Dlog.store=FILE" ^
-jar ./GreengrassInstaller/lib/Greengrass.jar ^
--trusted-plugin /path/to/com.example.CustomProvisioning.jar ^
--init-config ./GreengrassInstaller/config.yaml ^
--component-default-user ggc_user ^
--setup-system-service true
PowerShell
java -Droot="C:\greengrass\v2" "-Dlog.store=FILE" `
-jar ./GreengrassInstaller/lib/Greengrass.jar `
--trusted-plugin /path/to/com.example.CustomProvisioning.jar `
--init-config ./GreengrassInstaller/config.yaml `
--component-default-user ggc_user `
--setup-system-service true
If you specify --setup-system-service true, the installer prints Successfully set up
Nucleus as a system service if it set up and ran the software as a system service. Otherwise,
the installer doesn't output any message if it installs the software successfully.
Note
You can't use the deploy-dev-tools argument to deploy local development tools when
you run the installer without the --provision true argument. For information about
deploying the Greengrass CLI directly on your device, see Greengrass Command Line
Interface (p. 428).
4. Verify the installation by viewing the files in the root folder.
Linux or Unix
ls /greengrass/v2
Windows Command Prompt (CMD)
dir C:\greengrass\v2
PowerShell
ls C:\greengrass\v2
If the installation succeeded, the root folder contains several folders, such as config, packages,
and logs.
If you installed the AWS IoT Greengrass Core software as a system service, the installer runs the software
for you. Otherwise, you must run the software manually. For more information, see Run the AWS IoT
Greengrass Core software (p. 128).
For more information about how to configure and use the software and AWS IoT Greengrass, see the
following:
• Configure the AWS IoT Greengrass Core software (p. 157)
123
AWS IoT Greengrass Developer Guide, Version 2
Install with custom provisioning
• Develop AWS IoT Greengrass components (p. 440)
• Deploy AWS IoT Greengrass components to devices (p. 491)
• Greengrass Command Line Interface (p. 428)
Develop custom provisioning plugins
To develop a custom provisioning plugin, create a Java class that implements the
com.aws.greengrass.provisioning.DeviceIdentityInterface interface. You can include the
Greengrass nucleus JAR file in your project to access this interface and its classes. This interface defines
a method that inputs a plugin configuration and outputs a provisioning configuration. The provisioning
configuration defines configurations for the system and the Greengrass nucleus component (p. 181).
The AWS IoT Greengrass Core software installer uses this provisioning configuration to configure the
AWS IoT Greengrass Core software on a device.
After you develop a custom provisioning plugin, build it as a JAR file that you can provide to the AWS IoT
Greengrass Core software installer to run your plugin during installation. The installer runs your custom
provisioning plugin in the same JVM that the installer uses, so you can create a JAR that contains only
your plugin code.
Topics
• Requirements (p. 124)
• Implement the DeviceIdentityInterface interface (p. 124)
Requirements
To develop a custom provisioning plugin, you must create a Java class that meets the following
requirements:
• Uses the com.aws.greengrass package, or a package within the com.aws.greengrass package.
• Has a constructor without any arguments.
• Implements the DeviceIdentityInterface interface. For more information, see Implement the
DeviceIdentityInterface interface (p. 124).
Implement the DeviceIdentityInterface interface
To use the com.aws.greengrass.provisioning.DeviceIdentityInterface interface in your
custom plugin, add the Greengrass nucleus as a dependency to your project.
To use the DeviceIdentityInterface in a custom provisioning plugin project
• You can add the Greengrass nucleus JAR file as a library, or add the Greengrass nucleus as a Maven
dependency. Do one of the following:
• To add the Greengrass nucleus JAR file as a library, download the AWS IoT Greengrass Core
software, which contains the Greengrass nucleus JAR. You can download the latest version of
the AWS IoT Greengrass Core software from the following location:
• https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip
You can find the Greengrass nucleus JAR file (Greengrass.jar) in the lib folder in the ZIP
file. Add this JAR file to your project.
• To consume the Greengrass nucleus in a Maven project, add a dependency the on the nucleus
artifact in the com.aws.greengrass group. You must also add the greengrass-common
repository, because the Greengrass nucleus isn't available in the Maven Central Repository.
124
AWS IoT Greengrass Developer Guide, Version 2
Install with custom provisioning
<project ...>
...
<repositories>
<repository>
<id>greengrass-common</id>
<name>greengrass common</name>
<url>https://d2jrmugq4soldf.cloudfront.net/snapshots</url>
</repository>
</repositories>
...
<dependencies>
<dependency>
<groupId>com.aws.greengrass</groupId>
<artifactId>nucleus</artifactId>
<version>2.5.2-SNAPSHOT</version>
<scope>provided</scope>
</dependency>
</dependencies>
</project>
The DeviceIdentityInterface interface
The com.aws.greengrass.provisioning.DeviceIdentityInterface interface has the following
shape.
Note
You can also explore these classes in the com.aws.greengrass.provisioning package of the
Greengrass nucleus source code on GitHub.
public interface com.aws.greengrass.provisioning.DeviceIdentityInterface {
ProvisionConfiguration updateIdentityConfiguration(ProvisionContext context)
throws RetryableProvisioningException, InterruptedException;
// Return the name of the plugin.
String name();
}
com.aws.greengrass.provisioning.ProvisionConfiguration {
SystemConfiguration systemConfiguration;
NucleusConfiguration nucleusConfiguration
}
com.aws.greengrass.provisioning.ProvisionConfiguration.SystemConfiguration {
String certificateFilePath;
String privateKeyPath;
String rootCAPath;
String thingName;
}
com.aws.greengrass.provisioning.ProvisionConfiguration.NucleusConfiguration {
String awsRegion;
String iotCredentialsEndpoint;
String iotDataEndpoint;
String iotRoleAlias;
}
com.aws.greengrass.provisioning.ProvisioningContext {
Map<String, Object> parameterMap;
String provisioningPolicy; // The policy is always "PROVISION_IF_NOT_PROVISIONED".
}
125
AWS IoT Greengrass Developer Guide, Version 2
Installer arguments
com.aws.greengrass.provisioning.exceptions.RetryableProvisioningException {}
Each configuration value in the SystemConfiguration and NucleusConfiguration is required
to install the AWS IoT Greengrass Core software, but you can return null. If your custom provisioning
plugin returns null for any configuration value, you must provide that value in the system or nucleus
configuration when you create the config.yaml file to provide to the AWS IoT Greengrass Core
software installer. If your custom provisioning plugin returns a non-null value for an option that you also
define in config.yaml, then the installer replaces the value in config.yaml with the value returned
by the plugin.
Installer arguments
The AWS IoT Greengrass Core software includes an installer that sets up the software and provisions
the required AWS resources for the Greengrass core device to run. The installer includes the following
arguments that you can specify to configure the installation:
-h, --help
(Optional) Show the installer's help information.
--version
(Optional) Show the version of the AWS IoT Greengrass Core software.
-Droot
(Optional) The path to the folder to use as the root for the AWS IoT Greengrass Core software.
Note
This argument sets a JVM property, so you must specify it before -jar when you run the
installer. For example, specify java -Droot="/greengrass/v2" -jar /path/to/
Greengrass.jar.
Default:
• Linux: ~/.greengrass
• Windows: %USERPROFILE%/.greengrass
-ar, --aws-region
The AWS Region that the AWS IoT Greengrass Core software uses to retrieve or create its required
AWS resources.
-p, --provision
(Optional) You can register this device as an AWS IoT thing and provision the AWS resources that the
core device requires. If you specify true, the AWS IoT Greengrass Core software provisions an AWS
IoT thing, (optional) an AWS IoT thing group, an IAM role, and an AWS IoT role alias.
Default: false
-tn, --thing-name
(Optional) The name of the AWS IoT thing that you register as this core device. If the thing with the
name doesn't exist in your AWS account, the AWS IoT Greengrass Core software creates it.
Note
The thing name can't contain colon (:) characters.
You must specify --provision true to apply this argument.
Default: GreengrassV2IotThing_ plus a random UUID.
126
AWS IoT Greengrass Developer Guide, Version 2
Installer arguments
-tgn, --thing-group-name
(Optional) The name of the AWS IoT thing group where you add this core device's AWS IoT thing. If a
deployment targets this thing group, this core device receives that deployment when it connects to
AWS IoT Greengrass. If the thing group with this name doesn't exist in your AWS account, the AWS
IoT Greengrass Core software creates it.
Note
The thing group name can't contain colon (:) characters.
You must specify --provision true to apply this argument.
-tpn, --thing-policy-name
This feature is available for v2.4.0 and later of the Greengrass nucleus component (p. 181).
(Optional) The name of the AWS IoT policy to attach to this core device's AWS IoT thing certificate. If
the AWS IoT policy with this name doesn't exist in your AWS account, the AWS IoT Greengrass Core
software creates it.
The AWS IoT Greengrass Core software creates a permissive AWS IoT policy by default. You can
scope down this policy, or create a custom policy where you restrict permissions for your use case.
For more information, see Minimal AWS IoT policy for AWS IoT Greengrass V2 core devices (p. 777).
You must specify --provision true to apply this argument.
Default: GreengrassV2IoTThingPolicy
-trn, --tes-role-name
(Optional) The name of the IAM role to use to acquire AWS credentials that let the core device
interact with AWS services. If the role with this name doesn't exist in your AWS account, the AWS IoT
Greengrass Core software creates it with the GreengrassV2TokenExchangeRoleAccess policy.
This role doesn't have access to your S3 buckets where you host component artifacts. So, you must
add permissions to your artifacts' S3 buckets and objects when you create a component. For more
information, see Authorize core devices to interact with AWS services (p. 790).
You must specify --provision true to apply this argument.
Default: GreengrassV2TokenExchangeRole
-tra, --tes-role-alias-name
(Optional) The name of the AWS IoT role alias that points to the IAM role that provides AWS
credentials for this core device. If the role alias with this name doesn't exist in your AWS account, the
AWS IoT Greengrass Core software creates it and points it to the IAM role that you specify.
You must specify --provision true to apply this argument.
Default: GreengrassV2TokenExchangeRoleAlias
-ss, --setup-system-service
(Optional) You can set up the AWS IoT Greengrass Core software as a system service that runs when
this device boots. The system service name is greengrass. For more information, see Configure the
Greengrass nucleus as a system service (p. 158).
On Linux operating systems, this argument requires that the systemd init system is available on the
device.
Default: false
-u, --component-default-user
The name or ID of the user that the AWS IoT Greengrass Core software uses to run components. For
example, you can specify ggc_user. This value is required when you run the installer on Windows
operating systems.
127
AWS IoT Greengrass Developer Guide, Version 2
Run the AWS IoT Greengrass Core software
On Linux operating systems, you can also optionally specify the group. Specify the user and group
separated by a colon. For example, ggc_user:ggc_group.
The following additional considerations apply for Linux operating systems:
• If you run as root, the default component user is the user that is defined in the configuration
file. If the configuration file doesn't define a user, this defaults to ggc_user:ggc_group. If
ggc_user or ggc_group don't exist, the software creates them.
• If you run as a non-root user, the AWS IoT Greengrass Core software uses that user to run
components.
• If you don't specify a group, the AWS IoT Greengrass Core software uses the primary group of the
system user.
For more information, see Configure the user that runs components (p. 161).
-d, --deploy-dev-tools
(Optional) You can download and deploy the Greengrass CLI (p. 225) component to this core
device. You can use this tool to develop and debug components on this core device.
Important
We recommend that you use this component in only development environments, not
production environments. This component provides access to information and operations
that you typically won't need in a production environment. Follow the principle of least
privilege by deploying this component to only core devices where you need it.
You must specify --provision true to apply this argument.
Default: false
-init, --init-config
(Optional) The path to the configuration file to use to install the AWS IoT Greengrass Core software.
You can use this option to set up new core devices with a specific nucleus configuration, for example.
Important
The configuration file that you specify replaces the existing configuration file on the
core device. This erases the existing configuration, which includes the components and
component configurations on the core device.
-tp, --trusted-plugin
(Optional) The path to a JAR file to load as a trusted plugin. Use this option to provide provisioning
plugin JAR files, such as to install with fleet provisioning (p. 92) or custom provisioning (p. 117).
-s, --start
(Optional) You can start the AWS IoT Greengrass Core software after it installs and, optionally,
provisions resources.
Default: true
Run the AWS IoT Greengrass Core software
After you install the AWS IoT Greengrass Core software (p. 67), run it to connect your device to AWS
IoT Greengrass.
When you install the AWS IoT Greengrass Core software, you can specify whether to install it as a system
service with systemd. If you choose this option, the installer runs the software for you and configures it
to run when your device boots.
Topics
128
AWS IoT Greengrass Developer Guide, Version 2
Check if the AWS IoT Greengrass Core
software runs as a system service
• Check if the AWS IoT Greengrass Core software runs as a system service (p. 129)
• Run the AWS IoT Greengrass Core software as a system service (p. 130)
• Run the AWS IoT Greengrass Core software without a system service (p. 130)
Check if the AWS IoT Greengrass Core software runs
as a system service
When you install the AWS IoT Greengrass Core software, you can specify the --setup-system-
service true argument to install the AWS IoT Greengrass Core software as a system service. Linux
devices require the systemd init system to set up the AWS IoT Greengrass Core software as a system
service. If you use this option, the installer runs the software for you and configures it to run when
your device boots. The installer outputs the following message if it successfully installs the AWS IoT
Greengrass Core software as a system service.
Successfully set up Nucleus as a system service
If you previously installed the AWS IoT Greengrass Core software and don't have the installer output, you
can check if the software installed as a system service.
To check if the AWS IoT Greengrass Core software is installed as a system service
• Run the following command to check the status of the Greengrass system service.
Linux or Unix (systemd)
sudo systemctl status greengrass.service
The response looks similar to the following example if the AWS IoT Greengrass Core software is
installed as a system service and active.
# greengrass.service - Greengrass Core
Loaded: loaded (/etc/systemd/system/greengrass.service; enabled; vendor preset:
disabled)
Active: active (running) since Thu 2021-02-11 01:33:44 UTC; 4 days ago
Main PID: 16107 (sh)
CGroup: /system.slice/greengrass.service
##16107 /bin/sh /greengrass/v2/alts/current/distro/bin/loader
##16111 java -Dlog.store=FILE -Droot=/greengrass/v2 -jar /greengrass/v2/
alts/current/distro/lib/Greengrass...
If systemctl or greengrass.service isn't found, the AWS IoT Greengrass Core software
isn't installed as a system service. To run the software, see Run the AWS IoT Greengrass Core
software without a system service (p. 130).
Windows Command Prompt (CMD)
sc query greengrass
The response looks similar to the following example if the AWS IoT Greengrass Core software is
installed as a Windows service and active.
SERVICE_NAME: greengrass
TYPE : 10 WIN32_OWN_PROCESS
STATE : 4 RUNNING
129
AWS IoT Greengrass Developer Guide, Version 2
Run the AWS IoT Greengrass
Core software as a system service
(STOPPABLE, NOT_PAUSABLE, ACCEPTS_SHUTDOWN)
WIN32_EXIT_CODE : 0 (0x0)
SERVICE_EXIT_CODE : 0 (0x0)
CHECKPOINT : 0x0
WAIT_HINT : 0x0
PowerShell
Get-Service greengrass
The response looks similar to the following example if the AWS IoT Greengrass Core software is
installed as a Windows service and active.
Status Name DisplayName
------ ---- -----------
Running greengrass greengrass
Run the AWS IoT Greengrass Core software as a
system service
If the AWS IoT Greengrass Core software is installed as a system service, you can use the system service
manager to start, stop, and manage the software. For more information, see Configure the Greengrass
nucleus as a system service (p. 158).
To run the AWS IoT Greengrass Core software
• Run the following command to start the AWS IoT Greengrass Core software.
Linux or Unix (systemd)
sudo systemctl start greengrass.service
Windows Command Prompt (CMD)
sc start greengrass
PowerShell
Start-Service greengrass
Run the AWS IoT Greengrass Core software without a
system service
On Linux core devices, if the AWS IoT Greengrass Core software isn't installed as a system service, you
can run the software's loader script to run the software.
To run the AWS IoT Greengrass Core software without a system service
• Run the following command to start the AWS IoT Greengrass Core software. If you run this
command in a terminal, you must keep the terminal session open to keep the AWS IoT Greengrass
Core software running.
130
AWS IoT Greengrass Developer Guide, Version 2
Run AWS IoT Greengrass in Docker
• Replace /greengrass/v2 or C:\greengrass\v2 with the Greengrass root folder that you use.
sudo /greengrass/v2/alts/current/distro/bin/loader
The software prints the following message if it launches successfully.
Launched Nucleus successfully.
Run AWS IoT Greengrass Core software in a Docker
container
AWS IoT Greengrass can be configured to run in a Docker container. Docker is a platform that provides
the tools for you to build, run, test, and deploy applications that are based on Linux containers. When
you run an AWS IoT Greengrass Docker image, you can choose whether to provide your AWS credentials
to the Docker container and allow the AWS IoT Greengrass Core software installer to automatically
provision the AWS resources that a Greengrass core device requires to operate. If you don't want to
provide AWS credentials, then you can manually provision AWS resources and run AWS IoT Greengrass
Core software in the Docker container.
Topics
• Supported platforms and requirements (p. 131)
• AWS IoT Greengrass Docker software downloads (p. 132)
• Choose how to provision AWS resources (p. 133)
• Build the AWS IoT Greengrass container image from a Dockerfile (p. 133)
• Run AWS IoT Greengrass in a Docker container with automatic resource provisioning (p. 137)
• Run AWS IoT Greengrass in a Docker container with manual resource provisioning (p. 142)
• Troubleshooting AWS IoT Greengrass in a Docker container (p. 155)
Supported platforms and requirements
Host computers must meet the following minimum requirements to install and run the AWS IoT
Greengrass Core software in a Docker container:
• A Linux-based operating system with an internet connection.
• Docker Engine version 18.09 or later.
• (Optional) Docker Compose version 1.22 or later. Docker Compose is required only if you want to use
the Docker Compose CLI to run your Docker images.
To run Lambda function components inside of the Docker container, you must configure the container to
meet additional requirements. For more information, see Lambda function requirements (p. 64).
Run components in process mode
AWS IoT Greengrass doesn't support running Lambda functions or AWS-provided components in an
isolated runtime environment inside the AWS IoT Greengrass Docker container. You must run these
components in process mode without any isolation.
131
AWS IoT Greengrass Developer Guide, Version 2
Software downloads
When you configure a Lambda function component, set the isolation mode to No container. For more
information, see Run AWS Lambda functions (p. 523).
When you deploy any of the following AWS-provided components, update the configuration for each
component to set the containerMode parameter to NoContainer. For more information about
configuration updates, see Update component configurations (p. 500).
• CloudWatch metrics (p. 201)
• Device Defender (p. 230)
• Kinesis Data Firehose (p. 244)
• Modbus-RTU protocol adapter (p. 344)
• Amazon SNS (p. 389)
AWS IoT Greengrass Docker software downloads
AWS IoT Greengrass provides the following Dockerfile and Docker images that make it easier for you to
run AWS IoT Greengrass Core software in a Docker container.
Dockerfile
AWS IoT Greengrass provides a Dockerfile to build a container image that has AWS IoT Greengrass
Core software and dependencies installed on an Amazon Linux 2 (x86_64) base image. You can
modify the base image in the Dockerfile to run AWS IoT Greengrass on a different platform
architecture.
Download the Dockerfile package from GitHub.
For information about building the AWS IoT Greengrass container image from the Dockerfile, see
Build the AWS IoT Greengrass container image from a Dockerfile (p. 133).
Docker images
AWS IoT Greengrass provides a Docker image that has AWS IoT Greengrass Core software and
dependencies installed on an Amazon Linux 2 (x86_64) base image. To run AWS IoT Greengrass in
Docker on a different platform architecture, use the Dockerfile to build a container image for that
platform.
Download a prebuilt image from Docker Hub or Amazon Elastic Container Registry (Amazon ECR).
To pull the AWS IoT Greengrass Docker image from Docker Hub or Amazon ECR, run the following
command.
Docker Hub
docker pull amazon/aws-iot-greengrass:tag
Amazon ECR
docker pull public.ecr.aws/q3k3q7c1/aws-iot-greengrass-v2:tag
The version in your tag represents the version of the AWS IoT Greengrass Core software and
dependencies installed on the Amazon Linux 2 base image. To find tags for all available images, check
the Tags page on Docker Hub or the Image tags page on Amazon ECR.
132
AWS IoT Greengrass Developer Guide, Version 2
Choose how to provision AWS resources
Choose how to provision AWS resources
When you install the AWS IoT Greengrass Core software in a Docker container, you can choose whether
to automatically provision the AWS resources that a Greengrass core device requires to operate, or to use
resources that you manually provision.
• Automatic resource provisioning—The installer provisions the AWS IoT thing, AWS IoT thing group,
IAM role, and AWS IoT role alias when you run the AWS IoT Greengrass container image for the first
time. The installer can also deploy the local development tools to the core device, so you can use the
device to develop and test custom software components. To automatically provision these resources,
you must provide AWS credentials as environment variables to the Docker image.
To use automatic provisioning, you must set the Docker environment variable PROVISION=true and
mount a credential file to provide your AWS credentials to the container.
• Manual resource provisioning—If you don't want to provide AWS credentials to the container, then
you can manually provision the AWS resources before you run the AWS IoT Greengrass container
image. You must create a configuration file to provide information about these resources to the AWS
IoT Greengrass Core software installer within the Docker container.
To use manual provisioning, you must set the Docker environment variable PROVISION=false.
Manual provisioning is the default option.
For more information, see Build the AWS IoT Greengrass container image from a Dockerfile (p. 133).
Build the AWS IoT Greengrass container image from a
Dockerfile
AWS provides a Dockerfile that you can download and use to run AWS IoT Greengrass Core software in a
Docker container. Dockerfiles contain source code for building AWS IoT Greengrass container images.
Before you build an AWS IoT Greengrass container image, you must configure your Dockerfile to select
the version of AWS IoT Greengrass Core software that you want to install. You can also configure
environment variables to choose how to provision resources during installation, and customize other
installation options. This section describes how to configure and build an AWS IoT Greengrass Docker
image from a Dockerfile.
Download the Dockerfile package
You can download the AWS IoT Greengrass Dockerfile package from GitHub:
https://github.com/aws-greengrass/aws-greengrass-docker/releases
After you download the package, extract the contents to the download-directory/aws-
greengrass-docker-nucleus-version folder on your computer.
Specify the AWS IoT Greengrass Core software version
Use the following build argument in the Dockerfile to specify the version of the AWS IoT Greengrass Core
software that you want to use in the AWS IoT Greengrass Docker image. By default, the Dockerfile uses
the latest version of the AWS IoT Greengrass Core software.
GREENGRASS_RELEASE_VERSION
The version of the AWS IoT Greengrass Core software. By default, the Dockerfile downloads the
latest available version of the Greengrass nucleus. Set the value to the version of the nucleus that
you want to download.
133
AWS IoT Greengrass Developer Guide, Version 2
Build the AWS IoT Greengrass image from a Dockerfile
Set environment variables
Environment variables enable you to customize how AWS IoT Greengrass Core software is installed in
the Docker container. You can set environment variables for your AWS IoT Greengrass Docker image in
various ways.
• To use the same environment variables to create multiple images, set environment variables directly in
the Dockerfile.
• If you use docker run to start your container, pass environment variables as arguments in the
command, or set environment variables in an environment variables file and then pass the file as
an argument. For more information about setting environment variables in Docker, see the Docker
documentation.
• If you use docker-compose up to start your container, set environment variables in an environment
variables file and then pass the file as an argument. For more information about setting environment
variables in Compose, see the Docker documentation.
You can configure the following environment variables for the AWS IoT Greengrass Docker image.
Note
Don't modify the TINI_KILL_PROCESS_GROUP variable in the Dockerfile. This variable allows
forwarding SIGTERM to all PIDs in the PID group so that AWS IoT Greengrass Core software can
shut down correctly when the Docker container is stopped.
GGC_ROOT_PATH
(Optional) The path to the folder within the container to use as the root for AWS IoT Greengrass
Core software.
Default: /greengrass/v2
PROVISION
(Optional) Determines whether the AWS IoT Greengrass Core provisions AWS resources.
• If you specify true, AWS IoT Greengrass Core software registers the container image as an AWS
IoT thing and provisions the AWS resources that the Greengrass core device requires. The AWS IoT
Greengrass Core software provisions an AWS IoT thing, (optional) an AWS IoT thing group, an IAM
role, and an AWS IoT role alias. For more information, see Run AWS IoT Greengrass in a Docker
container with automatic resource provisioning (p. 137).
• If you specify false, then you must create a configuration file to provide to the AWS IoT
Greengrass Core installer that specifies to use the AWS resources and certificates that you
manually created. For more information, see Run AWS IoT Greengrass in a Docker container with
manual resource provisioning (p. 142).
Default: false
AWS_REGION
(Optional) The AWS Region that the AWS IoT Greengrass Core software uses to retrieve or create
required AWS resources.
Default: us-east-1.
THING_NAME
(Optional) The name of the AWS IoT thing that you register as this core device. If the thing with this
name doesn't exist in your AWS account, the AWS IoT Greengrass Core software creates it.
You must specify PROVISION=true to apply this argument.
Default: GreengrassV2IotThing_ plus a random UUID.
134
AWS IoT Greengrass Developer Guide, Version 2
Build the AWS IoT Greengrass image from a Dockerfile
THING_GROUP_NAME
(Optional) The name of the AWS IoT thing group where you add this core device's AWS IoT If
a deployment targets this thing group, this and other core devices in that group receive that
deployment when it connects to AWS IoT Greengrass. If the thing group with this name doesn't exist
in your AWS account, the AWS IoT Greengrass Core software creates it.
You must specify PROVISION=true to apply this argument.
TES_ROLE_NAME
(Optional) The name of the IAM role to use to acquire AWS credentials that let the Greengrass core
device interact with AWS services. If the role with this name doesn't exist in your AWS account, the
AWS IoT Greengrass Core software creates it with the GreengrassV2TokenExchangeRoleAccess
policy. This role doesn't have access to your S3 buckets where you host component artifacts. So, you
must add permissions to your artifacts' S3 buckets and objects when you create a component. For
more information, see Authorize core devices to interact with AWS services (p. 790).
Default: GreengrassV2TokenExchangeRole
TES_ROLE_ALIAS_NAME
(Optional) The name of the AWS IoT role alias that points to the IAM role that provides AWS
credentials for the Greengrass core device. If the role alias with this name doesn't exist in your AWS
account, the AWS IoT Greengrass Core software creates it and points it to the IAM role that you
specify.
Default: GreengrassV2TokenExchangeRoleAlias
COMPONENT_DEFAULT_USER
(Optional) The name or ID of the system user and group that the AWS IoT Greengrass Core software
uses to run components. Specify the user and group, separated by a colon. The group is optional. For
example, you can specify ggc_user:ggc_group or ggc_user.
• If you run as root, this defaults to the user and group that the configuration file defines. If the
configuration file doesn't define a user and group, this defaults to ggc_user:ggc_group. If
ggc_user or ggc_group don't exist, the software creates them.
• If you run as a non-root user, the AWS IoT Greengrass Core software uses that user to run
components.
• If you don't specify a group, the AWS IoT Greengrass Core software uses the primary group of the
system user.
For more information, see Configure the user that runs components (p. 161).
DEPLOY_DEV_TOOLS
(Optional) Defines whether to download and deploy the Greengrass CLI component (p. 225) in the
container image. You can use the Greengrass CLI to develop and debug components locally.
Important
We recommend that you use this component in only development environments, not
production environments. This component provides access to information and operations
that you typically won't need in a production environment. Follow the principle of least
privilege by deploying this component to only core devices where you need it.
Default: false
INIT_CONFIG
(Optional) The path to the configuration file to use to install the AWS IoT Greengrass Core software.
You can use this option to set up new Greengrass core devices with a specific nucleus configuration,
135
AWS IoT Greengrass Developer Guide, Version 2
Build the AWS IoT Greengrass image from a Dockerfile
or to specify manually provisioned resources, for example. You must mount your configuration file to
the path that you specify in this argument.
TRUSTED_PLUGIN
This feature is available for v2.4.0 and later of the Greengrass nucleus component (p. 181).
(Optional) The path to a JAR file to load as a trusted plugin. Use this option to provide provisioning
plugin JAR files, such as to install with fleet provisioning (p. 92) or custom provisioning (p. 117).
THING_POLICY_NAME
This feature is available for v2.4.0 and later of the Greengrass nucleus component (p. 181).
(Optional) The name of the AWS IoT policy to attach to this core device's AWS IoT thing certificate.
If the AWS IoT policy with this name doesn't exist in your AWS account the AWS IoT Greengrass Core
software creates it.
You must specify PROVISION=true to apply this argument.
Note
The AWS IoT Greengrass Core software creates a permissive AWS IoT policy by default. You
can scope down this policy, or create a custom policy where you restrict permissions for
your use case. For more information, see Minimal AWS IoT policy for AWS IoT Greengrass V2
core devices (p. 777).
Specify the dependencies to install
The RUN instruction in the AWS IoT Greengrass Dockerfile prepares up the container environment to run
the AWS IoT Greengrass Core software installer. You can customize the dependencies that are installed
before the AWS IoT Greengrass Core software installer runs in the Docker container.
Build the AWS IoT Greengrass image
Use the AWS IoT Greengrass Dockerfile to build an AWS IoT Greengrass container image. You can use the
Docker CLI or the Docker Compose CLI to build the image and start the container. You can also use the
Docker CLI to build the image and then use Docker Compose to start your container from that image.
Docker
1. On the host machine, run the following command to switch to the directory that contains the
configured Dockerfile.
cd download-directory/aws-greengrass-docker-nucleus-version
2. Run the following command to build the AWS IoT Greengrass container image from the
Dockerfile.
sudo docker build -t "platform/aws-iot-greengrass:nucleus-version" ./
Docker Compose
1. On the host machine, run the following command to switch to the directory that contains the
Dockerfile and the Compose file.
cd download-directory/aws-greengrass-docker-nucleus-version
136
AWS IoT Greengrass Developer Guide, Version 2
Run AWS IoT Greengrass in Docker
with automatic provisioning
2. Run the following command to use the Compose file to build the AWS IoT Greengrass container
image.
docker-compose -f docker-compose.yml build
You have successfully created the AWS IoT Greengrass container image. The Docker image has the AWS
IoT Greengrass Core software installed. You can now run the AWS IoT Greengrass Core software in a
Docker container.
Run AWS IoT Greengrass in a Docker container with
automatic resource provisioning
This tutorial shows you how to install and run AWS IoT Greengrass Core software in Docker container
with automatically provisioned AWS resources and local development tools. You can use this
development environment to explore AWS IoT Greengrass features in a Docker container.
Prerequisites
To complete this tutorial, you need the following.
• An AWS account. If you don't have one, see Set up an AWS account (p. 66).
• An AWS IAM user with permissions to provision the AWS IoT and IAM resources for a Greengrass core
device. The AWS IoT Greengrass Core software installer uses your AWS credentials to automatically
provision these resources. For information about the minimal IAM policy to automatically provision
resources, see Minimal IAM policy for installer to provision resources (p. 793).
• An AWS IoT Greengrass Docker image. This tutorial shows you how to pull the AWS IoT Greengrass
Docker image from Docker Hub. You can also pull the AWS IoT Greengrass Docker image (p. 132)
from Amazon Elastic Container Registry (Amazon ECR), or you can build an image from the AWS IoT
Greengrass Dockerfile (p. 133).
• A Linux-based operating system with an internet connection.
• Docker Engine version 18.09 or later.
• (Optional) Docker Compose version 1.22 or later. Docker Compose is required only if you want to use
the Docker Compose CLI to run your Docker images.
Configure your AWS credentials
In this step, you create a credential file on the host computer that contains your AWS security
credentials. When you run the AWS IoT Greengrass Docker image, you must mount the folder that
contains this credential file to /root/.aws/ in the Docker container. The AWS IoT Greengrass installer
uses these credentials to provision resources in your AWS account. For information about the minimal
IAM policy that the installer requires to automatically provision resources, see Minimal IAM policy for
installer to provision resources (p. 793).
1. Retrieve one of the following.
• Long-term credentials for an IAM user. For information about how to retrieve long-term
credentials, see Managing access keys for IAM users in the IAM User Guide.
• (Recommended) Temporary credentials for an IAM role. For information about how to retrieve
temporary credentials, see Using temporary security credentials with the AWS CLI in the IAM User
Guide.
137
AWS IoT Greengrass Developer Guide, Version 2
Run AWS IoT Greengrass in Docker
with automatic provisioning
2. Create a folder where you place your credential file.
mkdir ./greengrass-v2-credentials
3. Use a text editor to create a configuration file named credentials in the ./greengrass-v2-
credentials folder.
For example, you can run the following command to use GNU nano to create the credentials file.
nano ./greengrass-v2-credentials/credentials
4. Add your AWS credentials to the credentials file in the following format.
[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token = AQoEXAMPLEH4aoAH0gNCAPy...truncated...zrkuWJOgQs8IZZaIv2BXIa2R4Olgk
Include aws_session_token for temporary credentials only.
Note
Remove the credential file from the host computer after you start the AWS IoT Greengrass
container. If you don't remove the credential file, then your AWS credentials will remain
mounted inside the container. For more information, see Run the AWS IoT Greengrass Core
software in a container (p. 139).
Create an environment file
This tutorial uses an environment file to set the environment variables that will be passed to the AWS
IoT Greengrass Core software installer inside the Docker container. You can also use the -e or --env
argument in your docker run command to set environment variables in the Docker container or you
can set the variables in an environment block in the docker-compose.yml file.
1. Use a text editor to create an environment file named .env.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the .env in the current directory.
nano .env
2. Copy the following content into the file.
GGC_ROOT_PATH=/greengrass/v2
AWS_REGION=region
PROVISION=true
THING_NAME=MyGreengrassCore
THING_GROUP_NAME=MyGreengrassCoreGroup
TES_ROLE_NAME=GreengrassV2TokenExchangeRole
TES_ROLE_ALIAS_NAME=GreengrassCoreTokenExchangeRoleAlias
COMPONENT_DEFAULT_USER=ggc_user:ggc_group
Then, replace the following values.
• /greengrass/v2. The Greengrass root folder that you want to use for installation. You use the
GGC_ROOT environment variable to set this value.
• region. The AWS Region where you created the resources.
138
AWS IoT Greengrass Developer Guide, Version 2
Run AWS IoT Greengrass in Docker
with automatic provisioning
• MyGreengrassCore. The name of the AWS IoT thing. If the thing doesn't exist, the installer
creates it. The installer downloads the certificates to authenticate as the AWS IoT thing.
• MyGreengrassCoreGroup. The name of the AWS IoT thing group. If the thing group doesn't
exist, the installer creates it and adds the thing to it. If the thing group exists and has an active
deployment, the core device downloads and runs the software that the deployment specifies.
• GreengrassV2TokenExchangeRole. Replace with the name of the IAM token exchange
role that allows the Greengrass core device to get temporary AWS credentials. If the
role doesn't exist, the installer creates it and creates and attaches a policy named
GreengrassV2TokenExchangeRoleAccess. For more information, see Authorize core devices to
interact with AWS services (p. 790).
• GreengrassCoreTokenExchangeRoleAlias. The token exchange role alias. If the role alias
doesn't exist, the installer creates it and points it to the IAM token exchange role that you specify.
For more information, see
Note
You can set the DEPLOY_DEV_TOOLS environment variable to true to deploy the
Greengrass CLI component (p. 225), which enables you to develop custom components
inside of the Docker container. We recommend that you use this component in only
development environments, not production environments. This component provides access
to information and operations that you typically won't need in a production environment.
Follow the principle of least privilege by deploying this component to only core devices
where you need it.
Run the AWS IoT Greengrass Core software in a container
This tutorial shows you how to pull the latest AWS IoT Greengrass Docker image from Docker Hub and
start the Docker container. You can use the Docker CLI or the Docker Compose CLI to run the AWS IoT
Greengrass Core software image in a Docker container.
Docker
1. Run the following command to pull the latest AWS IoT Greengrass Docker image from Docker
Hub.
docker pull amazon/aws-iot-greengrass:latest
2. Run the following command to start the Docker container. This command runs the Greengrass
Docker image that you downloaded from Docker Hub. If you use a Docker image from a
different source, replace amazon/aws-iot-greengrass:latest with the name of your
Docker image.
docker run --rm --init -it --name aws-iot-greengrass \
-v path/to/greengrass-v2-credentials:/root/.aws/:ro \
--env-file .env \
-p 8883 \
amazon/aws-iot-greengrass:latest
This example command uses the following arguments for docker run:
• --rm. Cleans up the container when it exits.
• --init. Uses an init process in the container.
Note
The --init argument is required to shut down AWS IoT Greengrass Core software
when you stop the Docker container.
139
AWS IoT Greengrass Developer Guide, Version 2
Run AWS IoT Greengrass in Docker
with automatic provisioning
• -it. (Optional) Runs the Docker container in the foreground as an interactive process. You
can replace this with the -d argument to run the Docker container in detached mode instead.
For more information, see Detached vs foreground in the Docker documentation.
• --name. Runs a container named aws-iot-greengrass
• -v. Mounts a volume into the Docker container to make the configuration file and the
certificate files available to AWS IoT Greengrass running inside the container.
• --env-file. (Optional) Specifies the environment file to set the environment variables
that will be passed to the AWS IoT Greengrass Core software installer inside the Docker
container. This argument is required only if you created an environment file (p. 152) to set
environment variables. If you didn't create an environment file, you can use --env arguments
to set environment variables directly in your Docker run command.
• -p. (Optional) Publishes the 8883 container port to the host machine. This argument is
required if you want to connect and communicate over MQTT because AWS IoT Greengrass
uses port 8883 for MQTT traffic. To open other ports, use additional -p arguments.
Note
To run your Docker container with increased security, you can use the --cap-drop
and --cap-add arguments to selectively enable Linux capabilities for your container.
For more information, see Runtime privilege and Linux capabilities in the Docker
documentation.
3. Remove the credential file from path/to/greengrass-v2-credentials.
Docker Compose
1. Use a text editor to create a Docker Compose file named docker-compose.yml.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the docker-compose.yml in the current directory.
nano docker-compose.yml
Note
You can also download and use the latest version of the AWS-provided Compose file
from GitHub.
2. Add the following content to the Compose file. Your file should look similar to the following
example. This example specifies the Greengrass Docker image that you downloaded from
Docker Hub. If you use a Docker image from a different source, replace amazon/aws-iot-
greengrass:latest with the name of your Docker image.
version: '3.7'
services:
greengrass:
init: true
build:
context: .
container_name: aws-iot-greengrass
image: amazon/aws-iot-greengrass:latest
volumes:
- ./greengrass-v2-credentials:/root/.aws/:ro
env_file: .env
ports:
- "8883:8883"
The following parameters in this example Compose file are optional:
140
AWS IoT Greengrass Developer Guide, Version 2
Run AWS IoT Greengrass in Docker
with automatic provisioning
• ports—Publishes the 8883 container ports to the host machine. This parameter is required
if you want to connect and communicate over MQTT because AWS IoT Greengrass uses port
8883 for MQTT traffic.
• env_file—Specifies the environment file to set the environment variables that will be
passed to the AWS IoT Greengrass Core software installer inside the Docker container. This
parameter is required only if you created an environment file (p. 152) to set environment
variables. If you didn't create an environment file, you can use the environment parameter to
set the variables directly in your Compose file.
Note
To run your Docker container with increased security, you can use cap_drop and
cap_add in your Compose file to selectively enable Linux capabilities for your
container. For more information, see Runtime privilege and Linux capabilities in the
Docker documentation.
3. Run the following command start the Docker container.
docker-compose -f docker-compose.yml up
4. Remove the credential file from ./greengrass-v2-credentials.
Next steps
AWS IoT Greengrass Core software is now running in a Docker container. Run the following command to
retrieve the container ID for the currently running container.
docker ps
You can then run the following command to access the container and explore AWS IoT Greengrass Core
software running inside the container.
docker exec -it container-id /bin/bash
For information about creating a simple component, see Step 4: Develop and test a component on your
device (p. 42) in Getting started with AWS IoT Greengrass V2 (p. 31)
Note
When you use docker exec to run commands inside the Docker container, those commands
are not logged in the Docker logs. To log your commands in the Docker logs, attach an
interactive shell to the Docker container. For more information, see Attach an interactive shell to
the Docker container (p. 157).
The AWS IoT Greengrass Core log file is called greengrass.log and is located in /greengrass/
v2/logs. Component log files are also located in the same directory. To copy Greengrass logs to a
temporary directory on the host, run the following command:
docker cp container-id:/greengrass/v2/logs /tmp/logs
If you want to persist logs after a container exits or has been removed, we recommend that you bind-
mount only the /greengrass/v2/logs directory to the temporary logs directory on the host instead
of mounting the entire Greengrass directory. For more information, see Persist Greengrass logs outside
of the Docker container (p. 156).
To stop a running AWS IoT Greengrass Docker container, run docker stop or docker-compose -f
docker-compose.yml stop. This action sends SIGTERM to the Greengrass process and shuts down
141
AWS IoT Greengrass Developer Guide, Version 2
Run AWS IoT Greengrass in
Docker with manual provisioning
all associated processes that were started in the container. The Docker container is initialized with the
docker-init executable as process PID 1, which helps in removing any leftover zombie processes. For
more information, see the Docker documentation.
For information about troubleshooting issues with running AWS IoT Greengrass in a Docker container,
see Troubleshooting AWS IoT Greengrass in a Docker container (p. 155).
Run AWS IoT Greengrass in a Docker container with
manual resource provisioning
This tutorial shows you how to install and run AWS IoT Greengrass Core software in Docker container
with manually provisioned AWS resources.
Topics
• Prerequisites (p. 142)
• Create an AWS IoT thing (p. 76)
• Download the Amazon root certification authority (p. 146)
• Retrieve AWS IoT endpoints (p. 80)
• Create a token exchange role (p. 80)
• Create a configuration file (p. 151)
• Create an environment file (p. 152)
• Run the AWS IoT Greengrass Core software in a container (p. 152)
• Next steps (p. 141)
Prerequisites
To complete this tutorial, you need the following:
• An AWS account. If you don't have one, see Set up an AWS account (p. 66).
• An AWS IoT Greengrass Docker image. This tutorial shows you how to pull the AWS IoT Greengrass
Docker image from Docker Hub. You can also pull the AWS IoT Greengrass Docker image (p. 132)
from Amazon Elastic Container Registry (Amazon ECR), or you can build an image from the AWS IoT
Greengrass Dockerfile (p. 133).
• A Linux-based operating system with an internet connection.
• Docker Engine version 18.09 or later.
• (Optional) Docker Compose version 1.22 or later. Docker Compose is required only if you want to use
the Docker Compose CLI to run your Docker images.
Create an AWS IoT thing
AWS IoT things represent devices and logical entities that connect to AWS IoT. Greengrass core devices
are AWS IoT things. When you register a device as an AWS IoT thing, that device can use a digital
certificate to authenticate with AWS. This certificate allows the device to communicate with AWS IoT and
AWS IoT Greengrass.
In this section, you create an AWS IoT thing and download certificates that your device can use to
connect to AWS.
To create an AWS IoT thing
1. Create an AWS IoT thing for your device. On your development computer, run the following
command.
142
AWS IoT Greengrass Developer Guide, Version 2
Run AWS IoT Greengrass in
Docker with manual provisioning
• Replace MyGreengrassCore with the thing name to use. This name is also the name of your
Greengrass core device.
Note
The thing name can't contain colon (:) characters.
aws iot create-thing --thing-name MyGreengrassCore
The response looks similar to the following example, if the request succeeds.
{
"thingName": "MyGreengrassCore",
"thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyGreengrassCore",
"thingId": "8cb4b6cd-268e-495d-b5b9-1713d71dbf42"
}
2. Create a folder where you download the certificates for the AWS IoT thing.
mkdir greengrass-v2-certs
3. Create and download the certificates for the AWS IoT thing.
aws iot create-keys-and-certificate --set-as-active --certificate-pem-outfile
greengrass-v2-certs/device.pem.crt --public-key-outfile greengrass-v2-certs/
public.pem.key --private-key-outfile greengrass-v2-certs/private.pem.key
The response looks similar to the following example, if the request succeeds.
{
"certificateArn": "arn:aws:iot:us-west-2:123456789012:cert/
aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4",
"certificateId": "aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4",
"certificatePem": "-----BEGIN CERTIFICATE-----
MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w
0BAQUFADCBiDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZ
WF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIw
EAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5
jb20wHhcNMTEwNDI1MjA0NTIxWhcNMTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBh
MCVVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBb
WF6b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMx
HzAdBgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5jb20wgZ8wDQYJKoZIhvcNAQE
BBQADgY0AMIGJAoGBAMaK0dn+a4GmWIWJ21uUSfwfEvySWtC2XADZ4nB+BLYgVI
k60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9TrDHudUZg3qX4waLG5M43q7Wgc/MbQ
ITxOUSQv7c7ugFFDzQGBzZswY6786m86gpEIbb3OhjZnzcvQAaRHhdlQWIMm2nr
AgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4nUhVVxYUntneD9+h8Mg9q6q+auN
KyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0FkbFFBjvSfpJIlJ00zbhNYS5f6Guo
EDmFJl0ZxBHjJnyp378OD8uTs7fLvjx79LjSTbNYiytVbZPQUQ5Yaxu2jXnimvw
3rrszlaEXAMPLE=
-----END CERTIFICATE-----",
"keyPair": {
"PublicKey": "-----BEGIN PUBLIC KEY-----
\nMIIBIjANBgkqhkEXAMPLEQEFAAOCAQ8AMIIBCgKCAQEAEXAMPLE1nnyJwKSMHw4h
\nMMEXAMPLEuuN/dMAS3fyce8DW/4+EXAMPLEyjmoF/YVF/
gHr99VEEXAMPLE5VF13\n59VK7cEXAMPLE67GK+y+jikqXOgHh/xJTwo
+sGpWEXAMPLEDz18xOd2ka4tCzuWEXAMPLEahJbYkCPUBSU8opVkR7qkEXAMPLE1DR6sx2HocliOOLtu6Fkw91swQWEXAMPLE
\GB3ZPrNh0PzQYvjUStZeccyNCx2EXAMPLEvp9mQOUXP6plfgxwKRX2fEXAMPLEDa\nhJLXkX3rHU2xbxJSq7D
+XEXAMPLEcw+LyFhI5mgFRl88eGdsAEXAMPLElnI9EesG\nFQIDAQAB\n-----END PUBLIC KEY-----\n",
"PrivateKey": "-----BEGIN RSA PRIVATE KEY-----\nkey omitted for security reasons
\n-----END RSA PRIVATE KEY-----\n"
143
AWS IoT Greengrass Developer Guide, Version 2
Run AWS IoT Greengrass in
Docker with manual provisioning
}
}
4. Attach the certificate to the AWS IoT thing.
• Replace MyGreengrassCore with the name of your AWS IoT thing.
• Replace the certificate Amazon Resource Name (ARN) with the ARN of the certificate that you
created in the previous step.
aws iot attach-thing-principal --thing-name MyGreengrassCore
--principal arn:aws:iot:us-west-2:123456789012:cert/
aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4
The command doesn't have any output if the request succeeds.
5. Create and attach an AWS IoT policy that defines the AWS IoT permissions for your Greengrass core
device. The following policy allows access to all MQTT topics and Greengrass operations, so your
device works with custom applications and future changes that require new Greengrass operations.
You can restrict this policy down based on your use case. For more information, see Minimal AWS IoT
policy for AWS IoT Greengrass V2 core devices (p. 777).
If you have set up a Greengrass core device before, you can attach its AWS IoT policy instead of
creating a new one.
Do the following:
a. Create a file that contains the AWS IoT policy document that Greengrass core devices require.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano greengrass-v2-iot-policy.json
Copy the following JSON into the file.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish",
"iot:Subscribe",
"iot:Receive",
"iot:Connect",
"greengrass:*"
],
"Resource": [
"*"
]
}
]
}
b. Create an AWS IoT policy from the policy document.
• Replace GreengrassV2IoTThingPolicy with the name of the policy to create.
144
AWS IoT Greengrass Developer Guide, Version 2
Run AWS IoT Greengrass in
Docker with manual provisioning
aws iot create-policy --policy-name GreengrassV2IoTThingPolicy --policy-document
file://greengrass-v2-iot-policy.json
The response looks similar to the following example, if the request succeeds.
{
"policyName": "GreengrassV2IoTThingPolicy",
"policyArn": "arn:aws:iot:us-west-2:123456789012:policy/
GreengrassV2IoTThingPolicy",
"policyDocument": "{
\"Version\": \"2012-10-17\",
\"Statement\": [
{
\"Effect\": \"Allow\",
\"Action\": [
\"iot:Publish\",
\"iot:Subscribe\",
\"iot:Receive\",
\"iot:Connect\",
\"greengrass:*\"
],
\"Resource\": [
\"*\"
]
}
]
}",
"policyVersionId": "1"
}
c. Attach the AWS IoT policy to the AWS IoT thing's certificate.
• Replace GreengrassV2IoTThingPolicy with the name of the policy to attach.
• Replace the target ARN with the ARN of the certificate for your AWS IoT thing.
aws iot attach-policy --policy-name GreengrassV2IoTThingPolicy
--target arn:aws:iot:us-west-2:123456789012:cert/
aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4
The command doesn't have any output if the request succeeds.
6. (Optional) Add the AWS IoT thing to a new or existing thing group. You use thing groups to manage
fleets of Greengrass core devices. When you deploy software components to your devices, you can
choose to target individual devices or groups of devices. You can add a device to a thing group with
an active Greengrass deployment to deploy that thing group's software components to the device.
Do the following:
a. (Optional) Create an AWS IoT thing group.
• Replace MyGreengrassCoreGroup with the name of the thing group to create.
Note
The thing group name can't contain colon (:) characters.
aws iot create-thing-group --thing-group-name MyGreengrassCoreGroup
145
AWS IoT Greengrass Developer Guide, Version 2
Run AWS IoT Greengrass in
Docker with manual provisioning
The response looks similar to the following example, if the request succeeds.
{
"thingGroupName": "MyGreengrassCoreGroup",
"thingGroupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/
MyGreengrassCoreGroup",
"thingGroupId": "4df721e1-ff9f-4f97-92dd-02db4e3f03aa"
}
b. Add the AWS IoT thing to a thing group.
• Replace MyGreengrassCore with the name of your AWS IoT thing.
• Replace MyGreengrassCoreGroup with the name of the thing group.
aws iot add-thing-to-thing-group --thing-name MyGreengrassCore --thing-group-
name MyGreengrassCoreGroup
The command doesn't have any output if the request succeeds.
Download the Amazon root certification authority
In the previous step, you downloaded the certificates for your AWS IoT thing. In this step, you download
the Amazon root certificate authority (CA) certificate. AWS IoT certificates are associated with Amazon's
root CA certificate by default.
Run the following command to download the root CA certificate.
curl -o ./greengrass-v2-certs/AmazonRootCA1.pem https://www.amazontrust.com/repository/
AmazonRootCA1.pem
Retrieve AWS IoT endpoints
Get the AWS IoT endpoints for your AWS account, and save them to use later. Your device uses these
endpoints to connect to AWS IoT. Do the following:
1. Get the AWS IoT data endpoint for your AWS account.
aws iot describe-endpoint --endpoint-type iot:Data-ATS
The response looks similar to the following example, if the request succeeds.
{
"endpointAddress": "device-data-prefix-ats.iot.us-west-2.amazonaws.com"
}
2. Get the AWS IoT credentials endpoint for your AWS account.
aws iot describe-endpoint --endpoint-type iot:CredentialProvider
The response looks similar to the following example, if the request succeeds.
146
AWS IoT Greengrass Developer Guide, Version 2
Run AWS IoT Greengrass in
Docker with manual provisioning
"endpointAddress": "device-credentials-prefix.credentials.iot.us-
west-2.amazonaws.com"
}
Create a token exchange role
Greengrass core devices use an IAM service role, called the token exchange role, to authorize calls to AWS
services. The device uses the AWS IoT credentials provider to get temporary AWS credentials for this role,
which allows the device to interact with AWS IoT, send logs to Amazon CloudWatch Logs, and download
custom component artifacts from Amazon S3. For more information, see Authorize core devices to
interact with AWS services (p. 790).
You use an AWS IoT role alias to configure the token exchange role for Greengrass core devices. Role
aliases enable you to change the token exchange role for a device but keep the device configuration the
same. For more information, see Authorizing direct calls to AWS services in the AWS IoT Core Developer
Guide.
In this section, you create a token exchange IAM role and an AWS IoT role alias that points to the role.
If you have already set up a Greengrass core device, you can use its token exchange role and role alias
instead of creating new ones. Then, you configure your device's AWS IoT thing to use that role and alias.
To create a token exchange IAM role
1. Create an IAM role that your device can use as a token exchange role. Do the following:
a. Create a file that contains the trust policy document that the token exchange role requires.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano device-role-trust-policy.json
Copy the following JSON into the file.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "credentials.iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
b. Create the token exchange role with the trust policy document.
• Replace GreengrassV2TokenExchangeRole with the name of the IAM role to create.
aws iam create-role --role-name GreengrassV2TokenExchangeRole --assume-role-policy-
document file://device-role-trust-policy.json
The response looks similar to the following example, if the request succeeds.
147
AWS IoT Greengrass Developer Guide, Version 2
Run AWS IoT Greengrass in
Docker with manual provisioning
{
"Role": {
"Path": "/",
"RoleName": "GreengrassV2TokenExchangeRole",
"RoleId": "AROAZ2YMUHYHK5OKM77FB",
"Arn": "arn:aws:iam::123456789012:role/GreengrassV2TokenExchangeRole",
"CreateDate": "2021-02-06T00:13:29+00:00",
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "credentials.iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
}
c. Create a file that contains the access policy document that the token exchange role requires.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano device-role-access-policy.json
Copy the following JSON into the file.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:DescribeCertificate",
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:DescribeLogStreams",
"s3:GetBucketLocation"
],
"Resource": "*"
}
]
}
Note
This access policy doesn't allow access to component artifacts in S3 buckets. To deploy
custom components that define artifacts in Amazon S3, you must add permissions
to the role to allow your core device to retrieve component artifacts. For more
information, see Allow access to S3 buckets for component artifacts (p. 792).
If you don't yet have an S3 bucket for component artifacts, you can add these
permissions later after you create a bucket.
d. Create the IAM policy from the policy document.
• Replace GreengrassV2TokenExchangeRoleAccess with the name of the IAM policy to
create.
148
AWS IoT Greengrass Developer Guide, Version 2
Run AWS IoT Greengrass in
Docker with manual provisioning
aws iam create-policy --policy-name GreengrassV2TokenExchangeRoleAccess --policy-
document file://device-role-access-policy.json
The response looks similar to the following example, if the request succeeds.
{
"Policy": {
"PolicyName": "GreengrassV2TokenExchangeRoleAccess",
"PolicyId": "ANPAZ2YMUHYHACI7C5Z66",
"Arn": "arn:aws:iam::123456789012:policy/GreengrassV2TokenExchangeRoleAccess",
"Path": "/",
"DefaultVersionId": "v1",
"AttachmentCount": 0,
"PermissionsBoundaryUsageCount": 0,
"IsAttachable": true,
"CreateDate": "2021-02-06T00:37:17+00:00",
"UpdateDate": "2021-02-06T00:37:17+00:00"
}
}
e. Attach the IAM policy to the token exchange role.
• Replace GreengrassV2TokenExchangeRole with the name of the IAM role.
• Replace the policy ARN with the ARN of the IAM policy that you created in the previous step.
aws iam attach-role-policy --role-name GreengrassV2TokenExchangeRole --policy-
arn arn:aws:iam::123456789012:policy/GreengrassV2TokenExchangeRoleAccess
The command doesn't have any output if the request succeeds.
2. Create an AWS IoT role alias that points to the token exchange role.
• Replace GreengrassCoreTokenExchangeRoleAlias with the name of the role alias to create.
• Replace the role ARN with the ARN of the IAM role that you created in the previous step.
aws iot create-role-alias --role-alias GreengrassCoreTokenExchangeRoleAlias --role-
arn arn:aws:iam::123456789012:role/GreengrassV2TokenExchangeRole
The response looks similar to the following example, if the request succeeds.
{
"roleAlias": "GreengrassCoreTokenExchangeRoleAlias",
"roleAliasArn": "arn:aws:iot:us-west-2:123456789012:rolealias/
GreengrassCoreTokenExchangeRoleAlias"
}
Note
To create a role alias, you must have permission to pass the token exchange IAM role to
AWS IoT. If you receive an error message when you try to create a role alias, check that your
AWS user has this permission. For more information, see Granting a user permissions to
pass a role to an AWS service in the AWS Identity and Access Management User Guide.
3. Create and attach an AWS IoT policy that allows your Greengrass core device to use the role alias to
assume the token exchange role. If you have set up a Greengrass core device before, you can attach
its role alias AWS IoT policy instead of creating a new one. Do the following:
149
AWS IoT Greengrass Developer Guide, Version 2
Run AWS IoT Greengrass in
Docker with manual provisioning
a. (Optional) Create a file that contains the AWS IoT policy document that the role alias requires.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
nano greengrass-v2-iot-role-alias-policy.json
Copy the following JSON into the file.
• Replace the resource ARN with the ARN of your role alias.
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:AssumeRoleWithCertificate",
"Resource": "arn:aws:iot:us-west-2:123456789012:rolealias/
GreengrassCoreTokenExchangeRoleAlias"
}
]
}
b. Create an AWS IoT policy from the policy document.
• Replace GreengrassCoreTokenExchangeRoleAliasPolicy with the name of the AWS
IoT policy to create.
aws iot create-policy --policy-name GreengrassCoreTokenExchangeRoleAliasPolicy --
policy-document file://greengrass-v2-iot-role-alias-policy.json
The response looks similar to the following example, if the request succeeds.
{
"policyName": "GreengrassCoreTokenExchangeRoleAliasPolicy",
"policyArn": "arn:aws:iot:us-west-2:123456789012:policy/
GreengrassCoreTokenExchangeRoleAliasPolicy",
"policyDocument": "{
\"Version\":\"2012-10-17\",
\"Statement\": [
{
\"Effect\": \"Allow\",
\"Action\": \"iot:AssumeRoleWithCertificate\",
\"Resource\": \"arn:aws:iot:us-west-2:123456789012:rolealias/
GreengrassCoreTokenExchangeRoleAlias\"
}
]
}",
"policyVersionId": "1"
}
c. Attach the AWS IoT policy to the AWS IoT thing's certificate.
• Replace GreengrassCoreTokenExchangeRoleAliasPolicy with the name of the role
alias AWS IoT policy.
• Replace the target ARN with the ARN of the certificate for your AWS IoT thing.
150
AWS IoT Greengrass Developer Guide, Version 2
Run AWS IoT Greengrass in
Docker with manual provisioning
aws iot attach-policy --policy-name GreengrassCoreTokenExchangeRoleAliasPolicy
--target arn:aws:iot:us-west-2:123456789012:cert/
aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4
The command doesn't have any output if the request succeeds.
Create a configuration file
1. Create a folder where you place your configuration file.
mkdir ./greengrass-v2-config
2. Use a text editor to create a configuration file named config.yaml in the ./greengrass-v2-
config folder.
For example, you can run the following command to use GNU nano to create the config.yaml.
nano ./greengrass-v2-config/config.yaml
3. Copy the following YAML content into the file. This partial configuration file specifies system
parameters and Greengrass nucleus parameters.
---
system:
certificateFilePath: "/tmp/certs/device.pem.crt"
privateKeyPath: "/tmp/certs/private.pem.key"
rootCaPath: "/tmp/certs/AmazonRootCA1.pem"
rootpath: "/greengrass/v2"
thingName: "MyGreengrassCore"
services:
aws.greengrass.Nucleus:
componentType: "NUCLEUS"
version: "nucleus-version"
configuration:
awsRegion: "region"
iotRoleAlias: "GreengrassCoreTokenExchangeRoleAlias"
iotDataEndpoint: "device-data-prefix-ats.iot.region.amazonaws.com"
iotCredEndpoint: "device-credentials-prefix.credentials.region.amazonaws.com"
Then, replace the following values:
• /tmp/certs. The directory in the Docker container to which you mount the downloaded
certificates when you start the container.
• /greengrass/v2. The Greengrass root folder that you want to use for installation. You use the
GGC_ROOT environment variable to set this value.
• MyGreengrassCore. The name of the AWS IoT thing.
• nucleus-version. The version of the AWS IoT Greengrass Core software to install. This
value must match the version of the Docker image or Dockerfile that you downloaded. If you
downloaded the Greengrass Docker image with the latest tag, use docker inspect image-
id to see the image version.
• region. The AWS Region where you created your AWS IoT resources. You must also specify the
same value for the AWS_REGION environment variable in your environment file (p. 152).
• GreengrassCoreTokenExchangeRoleAlias. The token exchange role alias.
• device-data-prefix. The prefix for your AWS IoT data endpoint.
151
AWS IoT Greengrass Developer Guide, Version 2
Run AWS IoT Greengrass in
Docker with manual provisioning
• device-credentials-prefix. The prefix for your AWS IoT credentials endpoint.
Create an environment file
This tutorial uses an environment file to set the environment variables that will be passed to the AWS
IoT Greengrass Core software installer inside the Docker container. You can also use the -e or --env
argument in your docker run command to set environment variables in the Docker container or you
can set the variables in an environment block in the docker-compose.yml file.
1. Use a text editor to create an environment file named .env.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the .env in the current directory.
nano .env
2. Copy the following content into the file.
GGC_ROOT_PATH=/greengrass/v2
AWS_REGION=region
PROVISION=false
COMPONENT_DEFAULT_USER=ggc_user:ggc_group
INIT_CONFIG=/tmp/config/config.yaml
Then, replace the following values.
• /greengrass/v2. The path to the root folder to use to install the AWS IoT Greengrass Core
software.
• region. The AWS Region where you created your AWS IoT resources. You must specify the same
value for the awsRegion configuration parameter in your configuration file (p. 151).
• /tmp/config/. The directory to which you mount the configuration file when you start the
Docker container.
Note
You can set the DEPLOY_DEV_TOOLS environment variable to true to deploy the
Greengrass CLI component (p. 225), which enables you to develop custom components
inside of the Docker container. We recommend that you use this component in only
development environments, not production environments. This component provides access
to information and operations that you typically won't need in a production environment.
Follow the principle of least privilege by deploying this component to only core devices
where you need it.
Run the AWS IoT Greengrass Core software in a container
This tutorial shows you how to pull the latest AWS IoT Greengrass Docker image from Docker Hub and
start the Docker container. You can use the Docker CLI or the Docker Compose CLI to run the AWS IoT
Greengrass Core software image in a Docker container.
Docker
1. Run the following command to pull the latest AWS IoT Greengrass Docker image from Docker
Hub.
152
AWS IoT Greengrass Developer Guide, Version 2
Run AWS IoT Greengrass in
Docker with manual provisioning
docker pull amazon/aws-iot-greengrass:latest
2. Run the following command to start the Docker container. This command runs the Greengrass
Docker image that you downloaded from Docker Hub. If you use a Docker image from a
different source, replace amazon/aws-iot-greengrass:latest with the name of your
Docker image.
docker run --rm --init -it --name aws-iot-greengrass \
-v path/to/greengrass-v2-config:/tmp/config/:ro \
-v path/to/greengrass-v2-certs:/tmp/certs:ro \
--env-file .env \
-p 8883 \
amazon/aws-iot-greengrass:latest
This example command uses the following arguments for docker run:
• --rm. Cleans up the container when it exits.
• --init. Uses an init process in the container.
Note
The --init argument is required to shut down AWS IoT Greengrass Core software
when you stop the Docker container.
• -it. (Optional) Runs the Docker container in the foreground as an interactive process. You
can replace this with the -d argument to run the Docker container in detached mode instead.
For more information, see Detached vs foreground in the Docker documentation.
• --name. Runs a container named aws-iot-greengrass
• -v. Mounts a volume into the Docker container to make the configuration file and the
certificate files available to AWS IoT Greengrass running inside the container.
• --env-file. (Optional) Specifies the environment file to set the environment variables
that will be passed to the AWS IoT Greengrass Core software installer inside the Docker
container. This argument is required only if you created an environment file (p. 152) to set
environment variables. If you didn't create an environment file, you can use --env arguments
to set environment variables directly in your Docker run command.
• -p. (Optional) Publishes the 8883 container port to the host machine. This argument is
required if you want to connect and communicate over MQTT because AWS IoT Greengrass
uses port 8883 for MQTT traffic. To open other ports, use additional -p arguments.
Note
To run your Docker container with increased security, you can use the --cap-drop
and --cap-add arguments to selectively enable Linux capabilities for your container.
For more information, see Runtime privilege and Linux capabilities in the Docker
documentation.
Docker Compose
1. Use a text editor to create a Docker Compose file named docker-compose.yml.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the docker-compose.yml in the current directory.
nano docker-compose.yml
153
AWS IoT Greengrass Developer Guide, Version 2
Run AWS IoT Greengrass in
Docker with manual provisioning
Note
You can also download and use the latest version of the AWS-provided Compose file
from GitHub.
2. Add the following content to the Compose file. Your file should look similar to the following
example. This example specifies the Greengrass Docker image that you downloaded from
Docker Hub. If you use a Docker image from a different source, replace amazon/aws-iot-
greengrass:latest with the name of your Docker image.
version: '3.7'
services:
greengrass:
init: true
build:
context: .
container_name: aws-iot-greengrass
image: amazon/aws-iot-greengrass:latest
volumes:
- path/to/greengrass-v2-config:/tmp/config/:ro
- path/to/greengrass-v2-certs:/tmp/certs:ro
env_file: .env
ports:
- "8883:8883"
The following parameters in this example Compose file are optional:
• ports—Publishes the 8883 container ports to the host machine. This parameter is required
if you want to connect and communicate over MQTT because AWS IoT Greengrass uses port
8883 for MQTT traffic.
• env_file—Specifies the environment file to set the environment variables that will be
passed to the AWS IoT Greengrass Core software installer inside the Docker container. This
parameter is required only if you created an environment file (p. 152) to set environment
variables. If you didn't create an environment file, you can use the environment parameter to
set the variables directly in your Compose file.
Note
To run your Docker container with increased security, you can use cap_drop and
cap_add in your Compose file to selectively enable Linux capabilities for your
container. For more information, see Runtime privilege and Linux capabilities in the
Docker documentation.
3. Run the following command to start the container.
docker-compose -f docker-compose.yml up
Next steps
AWS IoT Greengrass Core software is now running in a Docker container. Run the following command to
retrieve the container ID for the currently running container.
docker ps
You can then run the following command to access the container and explore AWS IoT Greengrass Core
software running inside the container.
154
AWS IoT Greengrass Developer Guide, Version 2
Troubleshooting AWS IoT Greengrass in a Docker container
docker exec -it container-id /bin/bash
For information about creating a simple component, see Step 4: Develop and test a component on your
device (p. 42) in Getting started with AWS IoT Greengrass V2 (p. 31)
Note
When you use docker exec to run commands inside the Docker container, those commands
are not logged in the Docker logs. To log your commands in the Docker logs, attach an
interactive shell to the Docker container. For more information, see Attach an interactive shell to
the Docker container (p. 157).
The AWS IoT Greengrass Core log file is called greengrass.log and is located in /greengrass/
v2/logs. Component log files are also located in the same directory. To copy Greengrass logs to a
temporary directory on the host, run the following command:
docker cp container-id:/greengrass/v2/logs /tmp/logs
If you want to persist logs after a container exits or has been removed, we recommend that you bind-
mount only the /greengrass/v2/logs directory to the temporary logs directory on the host instead
of mounting the entire Greengrass directory. For more information, see Persist Greengrass logs outside
of the Docker container (p. 156).
To stop a running AWS IoT Greengrass Docker container, run docker stop or docker-compose -f
docker-compose.yml stop. This action sends SIGTERM to the Greengrass process and shuts down
all associated processes that were started in the container. The Docker container is initialized with the
docker-init executable as process PID 1, which helps in removing any leftover zombie processes. For
more information, see the Docker documentation.
For information about troubleshooting issues with running AWS IoT Greengrass in a Docker container,
see Troubleshooting AWS IoT Greengrass in a Docker container (p. 155).
Troubleshooting AWS IoT Greengrass in a Docker
container
Use the following information to help you troubleshoot issues with running AWS IoT Greengrass in a
Docker container and to debug issues with AWS IoT Greengrass in the Docker container.
Topics
• Troubleshooting issues with running the Docker container (p. 155)
• Debugging AWS IoT Greengrass in a Docker container (p. 156)
Troubleshooting issues with running the Docker container
Use the following information to help troubleshoot issues with running AWS IoT Greengrass in a Docker
container.
Topics
• Error: Cannot perform an interactive login from a non TTY device (p. 156)
• Error: Unknown options: -no-include-email (p. 156)
• Error: A firewall is blocking file Sharing between windows and the containers. (p. 156)
• Error: An error occurred (AccessDeniedException) when calling the GetAuthorizationToken
operation: User: arn:aws:iam::account-id:user/<user-name> is not authorized to perform:
ecr:GetAuthorizationToken on resource: * (p. 156)
155
AWS IoT Greengrass Developer Guide, Version 2
Troubleshooting AWS IoT Greengrass in a Docker container
• Error: You have reached your pull rate limit (p. 156)
Error: Cannot perform an interactive login from a non TTY device
This error can occur when you run the aws ecr get-login-password command. Make sure that you
installed the latest AWS CLI version 2 or version 1. We recommend that you use the AWS CLI version 2.
For more information, see Installing the AWS CLI in the AWS Command Line Interface User Guide.
Error: Unknown options: -no-include-email
This error can occur when you run the aws ecr get-login command. Make sure that you have the
latest AWS CLI version installed (for example, run: pip install awscli --upgrade --user). For
more information, see Installing the AWS Command Line Interface on Microsoft Windows in the AWS
Command Line Interface User Guide.
Error: A firewall is blocking file Sharing between windows and the containers.
You might receive this error or a Firewall Detected message when running Docker on a Windows
computer. This can also occur if you are signed in on a virtual private network (VPN) and your network
settings are preventing the shared drive from being mounted. In that situation, turn off VPN and re-run
the Docker container.
Error: An error occurred (AccessDeniedException) when calling the
GetAuthorizationToken operation: User: arn:aws:iam::account-id:user/<user-
name> is not authorized to perform: ecr:GetAuthorizationToken on resource: *
You might receive this error when running the aws ecr get-login-password command if you don't
have sufficient permissions to access an Amazon ECR repository. For more information, see Amazon ECR
Repository Policy Examples and Accessing One Amazon ECR Repository in the Amazon ECR User Guide.
Error: You have reached your pull rate limit
Docker Hub limits the number of pull requests that anonymous and Free Docker Hub users can make.
If you exceed the rate limits for anonymous or free user pull requests, then you receive one of the
following errors:
ERROR: toomanyrequests: Too Many Requests.
You have reached your pull rate limit.
To resolve these errors, you can wait for a few hours before you try another pull request. If you plan on
consistently submitting a large number of pull requests, see the Docker Hub website for information
about rate limits, and options for authenticating and upgrading your Docker account.
Debugging AWS IoT Greengrass in a Docker container
To debug issues with a Docker container, you can persist the Greengrass runtime logs or attach an
interactive shell to the Docker container.
Persist Greengrass logs outside of the Docker container
After you stop a AWS IoT Greengrass container, you can use the following docker cp command to
copy the Greengrass logs from the Docker container to a temporary logs directory.
156
AWS IoT Greengrass Developer Guide, Version 2
Configure the AWS IoT Greengrass Core software
docker cp container-id:/greengrass/v2/logs /tmp/logs
To persist logs even after a container exits or is removed, you must run the AWS IoT Greengrass Docker
container after bind-mounting the /greengrass/v2/logs directory.
To bind-mount the /greengrass/v2/logs directory, do one of the following when you run a new AWS
IoT Greengrass Docker container.
• Include -v /tmp/logs:/greengrass/v2/logs:ro in your docker run command.
Modify the volumes block in the Compose file to include the following line before you run your
docker-compose up command.
volumes:
- /tmp/logs:/greengrass/v2/logs:ro
You can then check your logs at /tmp/logs on your host to see Greengrass logs while AWS IoT
Greengrass is running inside the Docker container.
For information about running Greengrass Docker containers, see Run AWS IoT Greengrass in
Docker with manual provisioning (p. 142) and Run AWS IoT Greengrass in Docker with automatic
provisioning (p. 137)
Attach an interactive shell to the Docker container
When you use docker exec to run commands inside the Docker container, those commands are not
captured in the Docker logs. Logging your commands in the Docker logs can help you investigate the
state of the Greengrass Docker container. Do one of the following:
• Run the following command in a separate terminal to attach your terminal's standard input, output,
and error to the running container. This enables you to view and control the Docker container from
your current terminal.
docker attach container-id
• Run the following command in a separate terminal. This enables you to run your commands in
interactive mode, even if the container is not attached.
docker exec -it container-id sh -c "command > /proc/1/fd/1"
For general AWS IoT Greengrass troubleshooting, see Troubleshooting (p. 911).
Configure the AWS IoT Greengrass Core software
The AWS IoT Greengrass Core software provides options that you can use to configure the software. You
can create deployments to configure the AWS IoT Greengrass Core software on each core device.
Topics
• Deploy the Greengrass nucleus component (p. 158)
• Configure the Greengrass nucleus as a system service (p. 158)
• Control memory allocation with JVM options (p. 160)
• Configure the user that runs components (p. 161)
157
AWS IoT Greengrass Developer Guide, Version 2
Deploy the Greengrass nucleus component
• Configure system resource limits for components (p. 164)
• Connect on port 443 or through a network proxy (p. 165)
• Configure MQTT timeouts and cache settings (p. 170)
Deploy the Greengrass nucleus component
AWS IoT Greengrass provides the AWS IoT Greengrass Core software as a component that you can
deploy to your Greengrass core devices. You can create a deployment to apply the same configuration to
multiple Greengrass core devices. For more information, see Greengrass nucleus (p. 181) and Update
the AWS IoT Greengrass Core software (OTA) (p. 170).
Configure the Greengrass nucleus as a system service
You must configure the AWS IoT Greengrass Core software as a system service in your device's init
system to do the following:
• Start the AWS IoT Greengrass Core software when the device boots. This is a good practice if you
manage large fleets of devices.
• Install and run plugin components. Several AWS-provided components are plugin components,
which enables them to interface directly with the Greengrass nucleus. For more information about
component types, see Component types (p. 441).
• Apply over-the-air (OTA) updates to the core device's AWS IoT Greengrass Core software. For more
information, see Update the AWS IoT Greengrass Core software (OTA) (p. 170).
• Enable components to restart the AWS IoT Greengrass Core software or the core device when a
deployment updates the component to a new version or updates certain configuration parameters. For
more information, see the bootstrap lifecycle step (p. 476).
Topics
• Configure the nucleus as a system service (Linux) (p. 158)
• Configure the nucleus as a system service (Windows) (p. 159)
Configure the nucleus as a system service (Linux)
Linux devices support different init systems, such as initd, systemd, and SystemV. You use the --setup-
system-service true argument when you install the AWS IoT Greengrass Core software to start the
nucleus as a system service and configure it to launch when the device boots. The installer configures the
AWS IoT Greengrass Core software as a system service with systemd.
You can also manually configure the nucleus to run as a system service. The following example is a
service file for systemd.
[Unit]
Description=Greengrass Core
[Service]
Type=simple
PIDFile=/greengrass/v2/alts/loader.pid
RemainAfterExit=no
Restart=on-failure
RestartSec=10
ExecStart=/bin/sh /greengrass/v2/alts/current/distro/bin/loader
[Install]
158
AWS IoT Greengrass Developer Guide, Version 2
Configure the Greengrass nucleus as a system service
WantedBy=multi-user.target
For information about how to create and enable a service file for systemd on a Raspberry Pi, see systemd
Daemon in the Raspberry Pi documentation.
After you configure the system service, you can run the following commands to configure starting the
device on boot and to start or stop the AWS IoT Greengrass Core software.
• To check the status of the service (systemd)
sudo systemctl status greengrass.service
• To enable the nucleus to start when the device boots.
sudo systemctl enable greengrass.service
• To stop the nucleus from starting when the device boots.
sudo systemctl disable greengrass.service
• To start the AWS IoT Greengrass Core software.
sudo systemctl start greengrass.service
• To stop the AWS IoT Greengrass Core software.
sudo systemctl stop greengrass.service
Configure the nucleus as a system service (Windows)
You use the --setup-system-service true argument when you install the AWS IoT Greengrass Core
software to start the nucleus as a Windows service and configure it to launch when the device boots.
After you configure the service, you can run the following commands to configure starting the device
on boot and to start or stop the AWS IoT Greengrass Core software. You must run Command Prompt or
PowerShell as an administrator to run these commands.
Windows Command Prompt (CMD)
• To check the status of the service
sc query "greengrass"
• To enable the nucleus to start when the device boots.
sc config "greengrass" start=enabled
• To stop the nucleus from starting when the device boots.
sc config "greengrass" start=disabled
• To start the AWS IoT Greengrass Core software.
sc start "greengrass"
• To stop the AWS IoT Greengrass Core software.
159
AWS IoT Greengrass Developer Guide, Version 2
Control memory allocation with JVM options
sc stop "greengrass"
Note
On Windows devices, the AWS IoT Greengrass Core software ignores this shutdown signal
while it shuts down Greengrass component processes. If the AWS IoT Greengrass Core
software ignores the shutdown signal when you run this command, wait a few seconds,
and try again.
PowerShell
• To check the status of the service
Get-Service -Name "greengrass"
• To enable the nucleus to start when the device boots.
Set-Service -Name "greengrass" -Status stopped -StartupType enabled
• To stop the nucleus from starting when the device boots.
Set-Service -Name "greengrass" -Status stopped -StartupType disabled
• To start the AWS IoT Greengrass Core software.
Start-Service -Name "greengrass"
• To stop the AWS IoT Greengrass Core software.
Stop-Service -Name "greengrass"
Note
On Windows devices, the AWS IoT Greengrass Core software ignores this shutdown signal
while it shuts down Greengrass component processes. If the AWS IoT Greengrass Core
software ignores the shutdown signal when you run this command, wait a few seconds,
and try again.
Control memory allocation with JVM options
If you're running AWS IoT Greengrass on a device with limited memory, you can use Java virtual machine
(JVM) options to control the maximum heap size, garbage collection modes, and compiler options, which
control the amount of memory that AWS IoT Greengrass Core software uses. The heap size in the JVM
determines how much memory an application can use before garbage collection occurs, or before the
application runs out of memory. The maximum heap size specifies the maximum amount of memory the
JVM can allocate when expanding the heap during heavy activity.
To control memory allocation, create a new deployment or revise an existing deployment that includes
the nucleus component, and specify your JVM options in the jvmOptions configuration parameter in
the nucleus component configuration (p. 184).
Depending on your requirements, you can run AWS IoT Greengrass Core software with reduced memory
allocation or with minimum memory allocation.
Reduced memory allocation
160
AWS IoT Greengrass Developer Guide, Version 2
Configure the user that runs components
To run AWS IoT Greengrass Core software with reduced memory allocation, we recommend that you use
the following example configuration merge update to set JVM options in your nucleus configuration:
{
"jvmOptions": "-Xmx64m -XX:+UseSerialGC -XX:TieredStopAtLevel=1"
}
Minimum memory allocation
To run AWS IoT Greengrass Core software with minimum memory allocation, we recommend that you
use the following example configuration merge update to set JVM options in your nucleus configuration:
{
"jvmOptions": "-Xmx32m -XX:+UseSerialGC -Xint"
}
These example configuration merge updates use the following JVM options:
-XmxNNm
Sets the maximum JVM heap size.
For reduced memory allocation, use -Xmx64m as a starting value to limit the heap size to 64 MB. For
minimum memory allocation, use -Xmx32m as a starting value to limit the heap size to 32 MB.
You can increase or decrease the -Xmx value depending on your actual requirements; however, we
strongly recommend that you don't set the maximum heap size below 16 MB. If the maximum heap
size is too low for your environment, then the AWS IoT Greengrass Core software might encounter
unexpected errors because of insufficient memory.
-XX:+UseSerialGC
Specifies to use serial garbage collection for JVM heap space. The serial garbage collector is slower,
but uses less memory than other JVM garbage collection implementations.
-XX:TieredStopAtLevel=1
Instructs the JVM to use the Java just-in-time (JIT) compiler once. Because JIT compiled code uses
space in the device memory, using the JIT compiler more than once consumes more memory than a
single compilation.
-Xint
Instructs the JVM not to use the just-in-time (JIT) compiler. Instead, the JVM runs in interpreted-only
mode. This mode is slower than running JIT compiled code; however, the compiled code doesn't use
any space in memory.
For information about creating configuration merge updates, see Update component
configurations (p. 500).
Configure the user that runs components
The AWS IoT Greengrass Core software can run component processes as a system user and group
different from the one that runs the software. This increases security, because you can run the AWS
IoT Greengrass Core software as root, or as an administrator user, without giving those permissions to
components that run on the core device.
The following table indicates which types of components the AWS IoT Greengrass Core software can run
as a user that you specify. For more information, see Component types (p. 441).
161
AWS IoT Greengrass Developer Guide, Version 2
Configure the user that runs components
Component type Configure component user
Nucleus No
Plugin No
Generic Yes
Lambda (non-containerized) Yes
Lambda (containerized) Yes
You must create the component user before you can specify it in a deployment configuration. On
Windows-based devices, you must also store the user name and password for the user in the credential
manager instance of the LocalSystem account. For more information, see Set up a component user on
Windows devices (p. 163).
When you configure the component user on a Linux-based device, you can optionally also specify a
group. You specify the user and group separated by a colon (:) in the following format: user:group. If
you don't specify a group, the AWS IoT Greengrass Core software defaults to the primary group of the
user. You can use either the name or the ID to identify the user and group.
On Linux-based devices, you can also run components as a system user that doesn't exist, also called an
unknown user, to increase security. A Linux process can signal any other process that is run by the same
user. An unknown user doesn't run other processes, so you can run components as an unknown user to
prevent components from signaling other components on the core device. To run components as an
unknown user, specify a user ID that doesn't exist on the core device. You can also specify a group ID that
doesn't exist to run as an unknown group.
You can configure the user for each component and for each core device.
• Configure for a component
You can configure each component to run with a user specific to that component. When you create
a deployment, you can specify the user for each component in the runWith configuration for that
component. The AWS IoT Greengrass Core software runs components as the specified user if you
configure them. Otherwise, it defaults to run components as the default user that you configure
for the core device. For more information about specifying the component user in the deployment
configuration, see the runWith (p. 495) configuration parameter in Create deployments (p. 493).
• Configure default user for a core device
You can configure a default user that the AWS IoT Greengrass Core software uses to run components.
When the AWS IoT Greengrass Core software runs a component, it checks if you specified a user for
that component, and uses it to run the component. If the component doesn't specify a user, then the
AWS IoT Greengrass Core software runs the component as the default user that you configured for the
core device. For more information, see Configure the default component user (p. 163).
Note
On Windows-based devices, you must specify at least a default user to run components.
On Linux-based devices, the following considerations apply if you don't configure a user to run
components:
• If you run the AWS IoT Greengrass Core software as root, then the software won't run
components. You must specify a default user to run components if you run as root.
162
AWS IoT Greengrass Developer Guide, Version 2
Configure the user that runs components
• If you run the AWS IoT Greengrass Core software as a non-root user, then the software runs
components as that user.
Topics
• Set up a component user on Windows devices (p. 163)
• Configure the default component user (p. 163)
Set up a component user on Windows devices
To set up a component user on a Windows-based device
1. Create the component user in the LocalSystem account on the device.
net user /add component-user password
2. Use Microsoft's PsExec utility to store the user name and password for the component user in the
Credential Manager instance for the LocalSystem account.
psexec -s cmd /c cmdkey /generic:component-user /user:component-user /pass:password
Note
On Windows-based devices, the LocalSystem account runs the Greengrass nucleus, and you
must use the PsExec utility to store the component user information in the LocalSystem
account. Using the Credential Manager application stores this information in the Windows
account of the currently logged on user, instead of the LocalSystem account.
Configure the default component user
You can use a deployment to configure the default user on a core device. In this deployment, you update
the nucleus component (p. 181) configuration.
Note
You can also set the default user when you install the AWS IoT Greengrass Core software with
the --component-default-user option. For more information, see Install the AWS IoT
Greengrass Core software (p. 67).
Create a deployment (p. 493) that specifies the following configuration update for the
aws.greengrass.Nucleus component.
Linux
{
"runWithDefault": {
"posixUser": "ggc_user:ggc_group"
}
}
Windows
{
"runWithDefault": {
"windowsUser": "ggc_user"
}
}
163
AWS IoT Greengrass Developer Guide, Version 2
Configure system resource limits
Note
The user that you specify must exist, and the user name and password for this user must
be stored in the credential manager instance of the LocalSystem account on your Windows
device. For more information, see Set up a component user on Windows devices (p. 163).
The following example defines a deployment for a Linux-based device that configures ggc_user as the
default user and ggc_group as the default group. The merge configuration update requires a serialized
JSON object.
{
"components": {
"aws.greengrass.Nucleus": {
"version": "2.5.2",
"configurationUpdate": {
"merge": "{\"runWithDefault\":{\"posixUser\":\"ggc_user:ggc_group\"}}"
}
}
}
}
Configure system resource limits for components
Note
This feature is available for v2.4.0 and later of the Greengrass nucleus component (p. 181).
AWS IoT Greengrass doesn't currently support this feature on Windows core devices.
You can configure the maximum amount of CPU and RAM usage that each component's processes can
use on the core device.
The following table shows the types of components that support system resource limits. For more
information, see Component types (p. 441).
Component type Configure system resource limits
Nucleus No
Plugin No
Generic Yes
Lambda (non-containerized) Yes
Lambda (containerized) No
Important
System resource limits aren't supported when you run AWS IoT Greengrass Core software in a
Docker container (p. 131).
You can configure system resource limits for each component and for each core device.
• Configure for a component
You can configure each component with system resource limits specific to that component. When
you create a deployment, you can specify the system resource limits for each component in the
deployment. If the component supports system resource limits, the AWS IoT Greengrass Core software
164
AWS IoT Greengrass Developer Guide, Version 2
Connect on port 443 or through a network proxy
applies the limits to the component's processes. If you don't specify system resource limits for a
component, the AWS IoT Greengrass Core software uses any defaults that you have configured for the
core device. For more information, see Create deployments (p. 493).
• Configure defaults for a core device
You can configure the default system resource limits that the AWS IoT Greengrass Core software
applies to components that support these limits. When the AWS IoT Greengrass Core software
runs a component, it applies the system resource limits that you specify for that component. If that
component doesn't specify system resource limits, the the AWS IoT Greengrass Core software applies
the default system resource limits that you configure for the core device. If you don't specify default
system resource limits, the AWS IoT Greengrass Core software doesn't apply any system resource limits
by default. For more information, see Configure default system resource limits (p. 165).
Configure default system resource limits
You can deploy the Greengrass nucleus component (p. 181) to configure the default system resource
limits for a core device. To configure the default system resource limits, create a deployment (p. 493)
that specifies the following configuration update for the aws.greengrass.Nucleus component.
{
"runWithDefault": {
"systemResourceLimits": {
"cpu": cpuTimeLimit,
"memory": memoryLimitInKb
}
}
}
The following example defines a deployment that configures the CPU time limit to 2, which is equivalent
to 50% usage on a device with 4 CPU cores. This example also configures the memory usage to 100 MB.
{
"components": {
"aws.greengrass.Nucleus": {
"version": "2.5.2",
"configurationUpdate": {
"merge": "{\"runWithDefault\":{\"cpu\":2,\"memory\":102400}}"
}
}
}
}
Connect on port 443 or through a network proxy
AWS IoT Greengrass core devices communicate with AWS IoT Core using the MQTT messaging protocol
with TLS client authentication. By convention, MQTT over TLS uses port 8883. However, as a security
measure, restrictive environments might limit inbound and outbound traffic to a small range of TCP
ports. For example, a corporate firewall might open port 443 for HTTPS traffic, but close other ports that
are used for less common protocols, such as port 8883 for MQTT traffic. Other restrictive environments
might require all traffic to go through a proxy before connecting to the internet.
Note
Greengrass core devices that run Greengrass nucleus component (p. 181) v2.0.3 and earlier
use port 8443 to connect to the AWS IoT Greengrass data plane endpoint. These devices must
be able to connect to this endpoint on port 8443. For more information, see Allow device traffic
through a proxy or firewall (p. 807).
165
AWS IoT Greengrass Developer Guide, Version 2
Connect on port 443 or through a network proxy
To enable communication in these scenarios, AWS IoT Greengrass provides the following configuration
options:
• MQTT communication over port 443. If your network allows connections to port 443, you can
configure the Greengrass core device to use port 443 for MQTT traffic instead of the default port
8883. This can be a direct connection to port 443 or a connection through a network proxy server.
Unlike the default configuration, which uses certificate-based client authentication, MQTT on port 443
uses the device service role (p. 790) for authentication.
For more information, see Configure MQTT over port 443 (p. 166).
• HTTPS communication over port 443. The AWS IoT Greengrass Core software sends HTTPS traffic
over port 8443 by default, but you can configure it to use port 443. AWS IoT Greengrass uses the
Application Layer Protocol Network (ALPN) TLS extension to enable this connection. As with the
default configuration, HTTPS on port 443 uses certificate-based client authentication.
Important
To use ALPN and enable HTTPS communication over port 443, your core device must run Java
8 update 252 or later. All updates of Java version 9 and later also support ALPN.
For more information, see Configure HTTPS over port 443 (p. 167).
• Connection through a network proxy. You can configure a network proxy server to act as an
intermediary for connecting to the Greengrass core device. AWS IoT Greengrass supports basic
authentication for HTTP and HTTPS proxies.
Greengrass core devices must run Greengrass nucleus (p. 181) v2.5.0 or later to use HTTPS proxies.
The AWS IoT Greengrass Core software passes the proxy configuration to components through the
ALL_PROXY, HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables. Components must
use these settings to connect through the proxy. Components use common libraries (such as boto3,
cURL, and the python requests package) that typically use these environment variables by default
to make connections. If a component also specifies these environment variables, AWS IoT Greengrass
doesn't override them.
For more information, see Configure a network proxy (p. 167).
Configure MQTT over port 443
You can use a deployment to configure MQTT over port 443 on a single core device or a group of core
devices. In this deployment, you update the nucleus component (p. 181) configuration. The nucleus
restarts when you update its mqtt configuration.
To configure MQTT over port 443, create a deployment (p. 493) that specifies the following
configuration update for the aws.greengrass.Nucleus component.
{
"mqtt": {
"port": 443
}
}
The following example defines a deployment that configures MQTT over port 443. The merge
configuration update requires a serialized JSON object.
{
"components": {
"aws.greengrass.Nucleus": {
"version": "2.5.2",
"configurationUpdate": {
166
AWS IoT Greengrass Developer Guide, Version 2
Connect on port 443 or through a network proxy
"merge": "{\"mqtt\":{\"port\":443}}"
}
}
}
}
Configure HTTPS over port 443
This feature requires Greengrass nucleus (p. 181) v2.0.4 or later.
You can use a deployment to configure HTTPS over port 443 on a single core device or a group of core
devices. In this deployment, you update the nucleus component (p. 181) configuration.
To configure HTTPS over port 443, create a deployment (p. 493) that specifies the following
configuration update for the aws.greengrass.Nucleus component.
{
"greengrassDataPlanePort": 443
}
The following example defines a deployment that configures HTTPS over port 443. The merge
configuration update requires a serialized JSON object.
{
"components": {
"aws.greengrass.Nucleus": {
"version": "2.5.2",
"configurationUpdate": {
"merge": "{\"greengrassDataPlanePort\":443}"
}
}
}
}
Configure a network proxy
Follow the procedure in this section to configure Greengrass core devices to connect to the internet
through an HTTP or HTTPS network proxy. For more information about the endpoints and ports that
core devices use, see Allow device traffic through a proxy or firewall (p. 807).
Important
If your core device runs a version of the Greengrass nucleus (p. 181) earlier than v2.4.0, your
device's role must allow the following permissions to use a network proxy:
• iot:Connect
• iot:Publish
• iot:Receive
• iot:Subscribe
This is necessary because the device uses AWS credentials from the token exchange service
to authenticate MQTT connections to AWS IoT. The device uses MQTT to receive and install
deployments from the AWS Cloud, so your device won't work unless you define these
permissions on its role. Devices typically use X.509 certificates to authenticate MQTT
connections, but devices can't do this to authenticate when they use a proxy.
For more information about how to configure the device role, see Authorize core devices to
interact with AWS services (p. 790).
167
AWS IoT Greengrass Developer Guide, Version 2
Connect on port 443 or through a network proxy
You can use a deployment to configure a network proxy on a single core device or a group of core
devices. In this deployment, you update the nucleus component (p. 181) configuration. The nucleus
restarts when you update its networkProxy configuration.
To configure a network proxy, create a deployment (p. 493) for the aws.greengrass.Nucleus
component that merges the following configuration update. This configuration update contains the
networkProxy object (p. 169).
{
"networkProxy": {
"noProxyAddresses": "http://192.168.0.1,www.example.com",
"proxy": {
"url": "https://my-proxy-server:1100",
"username": "Mary_Major",
"password": "pass@word1357"
}
}
}
The following example defines a deployment that configures a network proxy. The merge configuration
update requires a serialized JSON object.
{
"components": {
"aws.greengrass.Nucleus": {
"version": "2.5.2",
"configurationUpdate": {
"merge": "{\"networkProxy\":{\"noProxyAddresses\":
\"http://192.168.0.1,www.example.com\",\"proxy\":{\"url\":\"https://my-proxy-server:1100\",
\"username\":\"Mary_Major\",\"password\":\"pass@word1357\"}}}"
}
}
}
}
Enable the core device to trust an HTTPS proxy
When you configure a core device to use an HTTPS proxy, you must add the proxy server certificate chain
to the core device's to enable it to trust the HTTPS proxy. Otherwise, the core device might encounter
errors when it tries to route traffic through the proxy. Add the proxy server CA certificate to the core
device's Amazon root CA certificate file.
To enable the core device to trust the HTTPS proxy
1. Find the Amazon root CA certificate file on the core device.
• If you installed the AWS IoT Greengrass Core software with automatic provisioning (p. 69), the
Amazon root CA certificate file exists at /greengrass/v2/rootCA.pem.
• If you installed the AWS IoT Greengrass Core software with manual (p. 76) or fleet
provisioning (p. 92), the Amazon root CA certificate file might exist at /greengrass/v2/
AmazonRootCA1.pem.
If the Amazon root CA certificate doesn't exist at these locations, check the system.rootCaPath
property in /greengrass/v2/config/effectiveConfig.yaml to find its location.
2. Add the contents of the proxy server CA certificate file to the Amazon root CA certificate file.
The following example shows a proxy server CA certificate added to the Amazon root CA certificate
file.
168
AWS IoT Greengrass Developer Guide, Version 2
Connect on port 443 or through a network proxy
-----BEGIN CERTIFICATE-----
MIIEFTCCAv2gAwIQWgIVAMHSAzWG/5YVRYtRQOxXUTEpHuEmApzGCSqGSIb3DQEK
\nCwUAhuL9MQswCQwJVUzEPMAVUzEYMBYGA1UECgwP1hem9uLmNvbSBJbmMuMRww
... content of proxy CA certificate ...
+vHIRlt0e5JAm5\noTIZGoFbK82A0/nO7f/t5PSIDAim9V3Gc3pSXxCCAQoFYnui
GaPUlGk1gCE84a0X\n7Rp/lND/PuMZ/s8YjlkY2NmYmNjMCAXDTE5MTEyN2cM216
gJMIADggEPADf2/m45hzEXAMPLE=
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIDQTCCAimgF6AwIBAgITBmyfz/5mjAo54vB4ikPmljZKyjANJmApzyMZFo6qBg
ADA5MQswCQYDVQQGEwJVUzEPMA0tMVT8QtPHRh8jrdkGA1UEChMGDV3QQDExBBKW
... content of root CA certificate ...
o/ufQJQWUCyziar1hem9uMRkwFwYVPSHCb2XV4cdFyQzR1KldZwgJcIQ6XUDgHaa
5MsI+yMRQ+hDaXJiobldXgjUka642M4UwtBV8oK2xJNDd2ZhwLnoQdeXeGADKkpy
rqXRfKoQnoZsG4q5WTP46EXAMPLE
-----END CERTIFICATE-----
The networkProxy object
Use the networkProxy object to specify information about the network proxy. This object contains the
following information:
noProxyAddresses
(Optional) A comma-separated list of IP addresses or host names that are exempt from the proxy.
proxy
The proxy to which to connect. This object contains the following information:
url
The URL of the proxy server in the format scheme://userinfo@host:port.
• scheme – The scheme, which must be http or https.
Important
Greengrass core devices must run Greengrass nucleus (p. 181) v2.5.0 or later to use
HTTPS proxies.
If you configure an HTTPS proxy, you must add the proxy server CA certificate to the
core device's Amazon root CA certificate. For more information, see Enable the core
device to trust an HTTPS proxy (p. 168).
• userinfo – (Optional) The user name and password information. If you specify this
information in the url, the Greengrass core device ignores the username and password
fields.
• host – The host name or IP address of the proxy server.
• port – (Optional) The port number. If you don't specify the port, then the Greengrass core
device uses the following default values:
• http – 80
• https – 443
Greengrass core devices must run Greengrass nucleus (p. 181) v2.5.0 or later to use HTTPS
proxies.
username
(Optional) The user name that authenticates the proxy server.
password
(Optional) The password that authenticates the proxy server.
169
AWS IoT Greengrass Developer Guide, Version 2
Configure MQTT timeouts and cache settings
Configure MQTT timeouts and cache settings
In the AWS IoT Greengrass environment, components can use MQTT to communicate with AWS IoT
Core. The AWS IoT Greengrass Core software manages MQTT messages for components. When the core
device loses connection to the AWS Cloud, the software caches MQTT messages to retry later when the
connection restores. You can configure settings such as message timeouts and the size of the cache.
For more information, see the mqtt and mqtt.spooler configuration parameters of the Greengrass
nucleus component (p. 181).
AWS IoT Core imposes service quotas on its MQTT message broker. These quotas might apply to
messages that you send between core devices and AWS IoT Core. For more information, see AWS IoT
Core message broker service quotas in the AWS General Reference.
Update the AWS IoT Greengrass Core software
(OTA)
The AWS IoT Greengrass Core software comprises the Greengrass nucleus component (p. 181) and
other optional components that you can deploy to your devices to perform over-the-air (OTA) updates of
the software. This feature is built in to the AWS IoT Greengrass Core software.
OTA updates make it more efficient to:
• Fix security vulnerabilities.
• Address software stability issues.
• Deploy new or improved features.
Topics
• Requirements (p. 170)
• Considerations for core devices (p. 170)
• Greengrass nucleus update behavior (p. 171)
• Perform an OTA update (p. 172)
Requirements
The following requirements apply to deploy OTA updates of the AWS IoT Greengrass Core software:
• The Greengrass core device must have a connection to the AWS Cloud to receive the deployment.
• The Greengrass core device must be correctly configured and provisioned with certificates and keys for
authentication with AWS IoT Core and AWS IoT Greengrass.
• The AWS IoT Greengrass Core software must be set up and running as a system service. OTA updates
don't work if you run the nucleus from the JAR file, Greengrass.jar. For more information, see
Configure the Greengrass nucleus as a system service (p. 158).
Considerations for core devices
Before perform an OTA update, be aware of the impact on the core devices that you update:
• The Greengrass nucleus shuts down.
170
AWS IoT Greengrass Developer Guide, Version 2
Greengrass nucleus update behavior
• All components running on the core device also shut down. If those components write to local
resources, they might leave those resources in an incorrect state unless shut down properly.
Components can use interprocess communication (p. 545) to tell the nucleus component to defer the
update until they clean up the resources that they use.
• While the nucleus component is shut down, the core device loses its connections with the AWS Cloud
and local devices.
• Long-lived Lambda functions that run as components lose their dynamic state information and drop
all pending work.
Greengrass nucleus update behavior
When you deploy a component, AWS IoT Greengrass installs the latest supported versions of all
component dependencies for that component. Because of this, new patch versions of AWS-provided
public components might be automatically deployed to your core devices if you add new devices to a
thing group, or you update the deployment that targets those devices. Some automatic updates, such as
a nucleus update, can cause your devices to restart unexpectedly.
When the version of the Greengrass nucleus component changes, the AWS IoT Greengrass Core software
—which includes the nucleus and all other components on your device—restarts to apply the changes.
Because of the impact on core devices when the nucleus component is updated, you might want to
control when a new nucleus patch version is deployed to your devices. To do so, you must directly
include the Greengrass nucleus component in your deployment. Directly including a component means
that you include a specific version of that component in your deployment configuration and do not rely
on component dependencies to deploy that component to your devices. For more information about
defining dependencies in your component recipes, see Recipe format (p. 472).
Review the following table to understand the update behavior for the Greengrass nucleus component
based on your actions and deployment configurations.
Action Deployment configuration Nucleus update behavior
Add new devices to a thing The deployment does not On new devices, installs the
group targeted by an existing directly include Greengrass latest patch version of nucleus
deployment without revising the nucleus. that meets all component
deployment. dependency requirements.
The deployment directly
includes at least one AWS- On existing devices, does not
provided component, or includes update the installed version of
a custom component that the nucleus.
depends on an AWS-provided
component or on the Greengrass
nucleus.
Add new devices to a thing The deployment directly On new devices, installs the
group targeted by an existing includes a specific version of the specified nucleus version.
deployment without revising the Greengrass nucleus.
deployment. On existing devices, does not
update the installed version of
the nucleus.
Create a new deployment or The deployment does not On all targeted devices, installs
revise an existing deployment. directly include Greengrass the latest patch version of
nucleus. the nucleus that meets all
component dependency
171
AWS IoT Greengrass Developer Guide, Version 2
Perform an OTA update
Action Deployment configuration Nucleus update behavior
The deployment directly requirements, including on any
includes at least one AWS- new devices that you add to the
provided component, or includes targeted thing group.
a custom component that
depends on an AWS-provided
component or on the Greengrass
nucleus.
Create a new deployment or The deployment directly On all targeted devices, installs
revise an existing deployment. includes a specific version of the the specified nucleus version,
Greengrass nucleus. including any new devices that
you add to the targeted thing
group.
Perform an OTA update
To perform an OTA update, create a deployment (p. 493) that includes the nucleus
component (p. 181) and the version to install.
Uninstall the AWS IoT Greengrass Core software
You can uninstall the AWS IoT Greengrass Core software to remove it from a device that you don't want
to use as a Greengrass core device. You can also use these steps to clean up an installation that fails.
To uninstall the AWS IoT Greengrass Core software
1. If you run the software as a system service, you must stop, disable, and remove the service. Run the
following commands as appropriate for your operating system.
Linux
1. Stop the service.
sudo systemctl stop greengrass.service
2. Disable the service.
sudo systemctl disable greengrass.service
3. Remove the service.
sudo rm /etc/systemd/system/greengrass.service
4. Verify that the service is deleted.
sudo systemctl daemon-reload && sudo systemctl reset-failed
172
AWS IoT Greengrass Developer Guide, Version 2
Uninstall the AWS IoT Greengrass Core software
Windows (Command Prompt)
Note
You must run Command Prompt as an administrator to run these commands.
1. Stop the service.
sc stop "greengrass"
2. Disable the service.
sc config "greengrass" start=disabled
3. Remove the service.
sc delete "greengrass"
4. Restart the device.
Windows (PowerShell)
Note
You must run PowerShell as an administrator to run these commands.
1. Stop the service.
Stop-Service -Name "greengrass"
2. Disable the service.
Set-Service -Name "greengrass" -Status stopped -StartupType disabled
3. Remove the service.
• For PowerShell 6.0 and later:
Remove-Service -Name "greengrass" -Confirm:$false -Verbose
• For PowerShell versions earlier than 6.0 :
Get-Item HKLM:\SYSTEM\CurrentControlSet\Services\greengrass | Remove-Item -
Force -Verbose
4. Restart the device.
2. Remove the root folder from the device. Replace /greengrass/v2 or C:\greengrass\v2 with
the path to the root folder.
Linux
sudo rm -rf /greengrass/v2
Windows (Command Prompt)
rmdir /s /q C:\greengrass\v2
173
AWS IoT Greengrass Developer Guide, Version 2
Uninstall the AWS IoT Greengrass Core software
Windows (PowerShell)
Remove-Item -Path C:\greengrass\v2 -Recurse -Force
3. Delete the core device from the AWS IoT Greengrass service. This step removes the core device's
status information from the AWS Cloud. Be sure to complete this step if you plan to reinstall the
AWS IoT Greengrass Core software to a core device with the same name.
• To delete a core device from the AWS IoT Greengrass console, do the following:
a. Navigate to the AWS IoT Greengrass console.
b. Choose Core devices.
c. Choose the core device to delete.
d. Choose Delete.
e. In the confirmation modal, choose Delete.
• To delete a core device with the AWS Command Line Interface, use the DeleteCoreDevice
operation. Run the following command, and replace MyGreengrassCore with the name of the
core device.
aws greengrassv2 delete-core-device --core-device-thing-name MyGreengrassCore
174
AWS IoT Greengrass Developer Guide, Version 2
AWS-provided components
AWS IoT Greengrass provides and maintains prebuilt components that you can deploy to your devices.
These components include features (such as stream manager), AWS IoT Greengrass V1 connectors (such
as CloudWatch metrics), and local development tools (such as the AWS IoT Greengrass CLI). You can
deploy these components (p. 491) to your devices for their standalone functionality, or you can use
them as dependencies in your custom Greengrass components (p. 440).
Note
Several AWS-provided components depend on specific minor versions of the Greengrass
nucleus. Because of this dependency, you need to update these components when you update
the Greengrass nucleus to a new minor version. For information about the specific versions
of the nucleus that each component depends on, see the corresponding component topic.
For more information about updating the nucleus, see Update the AWS IoT Greengrass Core
software (OTA) (p. 170).
Component Description Depends Component Supported Open
on type (p. 441)OS source (p. 921)
nucleus
Greengrass nucleus (p. 181) The nucleus - Nucleus Linux, Yes
of the Windows
AWS IoT
Greengrass
Core
software.
Use this
component
to configure
and update
the software
on your core
devices.
Client device auth (p. 194) Enables local Yes Plugin Linux, Yes
IoT devices, Windows
called client
devices, to
connect to
the core
device.
CloudWatch metrics (p. 201) Publishes Yes Lambda Linux, No
custom Windows
metrics to
Amazon
CloudWatch.
AWS IoT Device Notifies Yes Lambda Linux, No
Defender (p. 230) administrators Windows
of changes
in the state
of the
Greengrass
core device
175
AWS IoT Greengrass Developer Guide, Version 2
Component Description Depends Component Supported Open
on type (p. 441)OS source (p. 921)
nucleus
to identify
unusual
behavior.
Docker application Enables Yes Generic Linux, No
manager (p. 216) AWS IoT Windows
Greengrass
to download
Docker
images from
Docker Hub
and Amazon
Elastic
Container
Registry
(Amazon
ECR).
Edge connector for Kinesis Video Reads video Yes Generic Linux No
Streams (p. 220) feeds from
local cameras,
publishes the
streams to
Kinesis Video
Streams,
and displays
the streams
in Grafana
dashboards
with AWS IoT
TwinMaker.
Greengrass CLI (p. 225) Provides a Yes Plugin Linux, Yes
command- Windows
line interface
that you
can use to
create local
deployments
and interact
with the
Greengrass
core device
and its
components.
176
AWS IoT Greengrass Developer Guide, Version 2
Component Description Depends Component Supported Open
on type (p. 441)OS source (p. 921)
nucleus
IP detector (p. 240) Reports Yes Plugin Linux, Yes
MQTT broker Windows
connectivity
information
to AWS IoT
Greengrass,
so client
devices can
discover how
to connect.
Kinesis Data Firehose (p. 244) Publishes Yes Lambda Linux No
data through
Amazon
Kinesis Data
Firehose
delivery
streams to
destinations
in the AWS
Cloud.
Lambda launcher (p. 252) Handles No Generic Linux No
processes and
environment
configuration
for Lambda
functions.
Lambda manager (p. 255) Handles Yes Plugin Linux No
interprocess
communication
and scaling
for Lambda
functions.
Lambda runtimes (p. 258) Provides No Generic Linux No
artifacts for
each Lambda
runtime.
Legacy subscription Manages Yes Generic Linux No
router (p. 260) subscriptions
for Lambda
functions
that run on
AWS IoT
Greengrass
V1.
177
AWS IoT Greengrass Developer Guide, Version 2
Component Description Depends Component Supported Open
on type (p. 441)OS source (p. 921)
nucleus
Local debug console (p. 265) Provides a Yes Plugin Linux, Yes
local console Windows
that you
can use to
debug and
manage the
Greengrass
core device
and its
components.
Log manager (p. 273) Collects and Yes Plugin Linux, Yes
uploads Windows
logs on the
Greengrass
core device.
Machine learning Provides See Machine learning components (p. 288).
components (p. 288) machine
learning
models
and sample
inference
code that
you can use
to perform
machine
learning
inference on
Greengrass
core devices.
Modbus-RTU protocol Polls Yes Lambda Linux No
adapter (p. 344) information
from local
Modbus RTU
devices.
Nucleus telemetry Publishes Yes Plugin Linux, Yes
emitter (p. 368) system health Windows
telemetry
data gathered
from the
nucleus to a
local topic or
to an AWS IoT
Core MQTT
topic.
178
AWS IoT Greengrass Developer Guide, Version 2
Component Description Depends Component Supported Open
on type (p. 441)OS source (p. 921)
nucleus
MQTT bridge (p. 360) Relays MQTT No Plugin Linux, Yes
messages Windows
between
client devices,
local AWS IoT
Greengrass
publish/
subscribe, and
AWS IoT Core.
MQTT broker Handles No Plugin Linux, Yes
(Moquette) (p. 365) MQTT Windows
messages
between
client devices
and the core
device.
Secret manager (p. 374) Deploys Yes Plugin Linux, Yes
secrets from Windows
AWS Secrets
Manager
secrets so
that you can
securely use
credentials,
such as
passwords,
in custom
components
on the
Greengrass
core device.
Secure tunneling (p. 379) Enables AWS Yes Generic Linux No
IoT secure
tunneling
connections
that you
can use to
establish
bidrectional
communications
with
Greengrass
core devices
that are
behind
restricted
firewalls.
179
AWS IoT Greengrass Developer Guide, Version 2
Component Description Depends Component Supported Open
on type (p. 441)OS source (p. 921)
nucleus
Shadow manager (p. 383) Enables Yes Plugin Linux, Yes
interaction Windows
with shadows
on the core
device. It
manages
shadow
document
storage and
also the
synchronization
of local
shadow states
with the AWS
IoT Device
Shadow
service.
Amazon SNS (p. 389) Publishes Yes Lambda Linux No
messages to
Amazon SNS
topics.
Stream manager (p. 398) Streams high- Yes Generic Linux, No
volume data Windows
from local
sources to the
AWS Cloud.
Systems Manager Manage the Yes Generic Linux No
Agent (p. 403) core device
with AWS
Systems
Manager,
which enables
you to patch
devices, run
commands,
and more.
Token exchange service (p. 407) Provides AWS No Generic Linux, No
credentials Windows
that you
can use to
interact with
AWS services.
IoT SiteWise OPC-UA Collects data Yes Generic Linux No
collector (p. 409) from OPC-UA
servers.
IoT SiteWise publisher (p. 411) Publishes Yes Generic Linux No
data to the
AWS Cloud.
180
AWS IoT Greengrass Developer Guide, Version 2
Greengrass nucleus
Component Description Depends Component Supported Open
on type (p. 441)OS source (p. 921)
nucleus
IoT SiteWise processor (p. 414) Processes Yes Generic Linux No
data on the
Greengrass
core devices.
Greengrass nucleus
The Greengrass nucleus component (aws.greengrass.Nucleus) is a mandatory component and the
minimum requirement to run the AWS IoT Greengrass Core software on a device. You can configure
this component to customize and update your AWS IoT Greengrass Core software remotely. Deploy this
component to configure settings such as proxy, device role, and AWS IoT thing configuration on your
core devices.
Important
When the version of the nucleus component changes, or when you change certain configuration
parameters, the AWS IoT Greengrass Core software—which includes the nucleus and all other
components on your device—restarts to apply the changes.
When you deploy a component, AWS IoT Greengrass installs the latest supported versions of
all component dependencies for that component. Because of this, new patch versions of AWS-
provided public components might be automatically deployed to your core devices if you add
new devices to a thing group, or you update the deployment that targets those devices. Some
automatic updates, such as a nucleus update, can cause your devices to restart unexpectedly.
To prevent unintended updates for a component that is running on your device, we recommend
that you directly include your preferred version of that component when you create a
deployment (p. 493). For more information about update behavior for AWS IoT Greengrass
Core software, see Update the AWS IoT Greengrass Core software (OTA) (p. 170).
Topics
• Versions (p. 181)
• Operating system (p. 182)
• Requirements (p. 182)
• Dependencies (p. 182)
• Installation (p. 182)
• Configuration (p. 182)
• Local log file (p. 189)
• Changelog (p. 190)
Versions
This component has the following versions:
• 2.5.x
• 2.4.x
• 2.3.x
• 2.2.x
• 2.1.x
• 2.0.x
181
AWS IoT Greengrass Developer Guide, Version 2
Operating system
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
For more information, see Supported platforms (p. 62).
Requirements
Devices must meet certain requirements to install and run the Greengrass nucleus and the AWS IoT
Greengrass Core software. For more information, see Device requirements (p. 63).
Dependencies
The Greengrass nucleus does not include any component dependencies. However, several AWS-
provided components include the nucleus as a dependency. For more information, see AWS-provided
components (p. 175).
For more information about component dependencies, see the component recipe reference (p. 473).
Installation
You can download an installer that sets up the Greengrass nucleus component on your device. This
installer sets up your device as a Greengrass core device. There are two types of installations that you can
perform: a quick installation that creates required AWS resources for you, or a manual installation where
you create the AWS resources yourself. For more information, see Install the AWS IoT Greengrass Core
software (p. 67).
You can also follow a tutorial to install the Greengrass nucleus and explore Greengrass component
development. For more information, see Getting started with AWS IoT Greengrass V2 (p. 31).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component. Some parameters require that the AWS IoT Greengrass Core software restarts to
take effect. For more information about why and how to configure this component, see Configure the
AWS IoT Greengrass Core software (p. 157).
iotRoleAlias
The AWS IoT role alias that points to a token exchange IAM role. The AWS IoT credentials provider
assumes this role to allow the Greengrass core device to interact with AWS services. For more
information, see Authorize core devices to interact with AWS services (p. 790).
When you run the AWS IoT Greengrass Core software with the --provision true option, the
software provisions a role alias and sets its value in the nucleus component.
networkProxy
(Optional) The network proxy to use for all connections. For more information, see Connect on port
443 or through a network proxy (p. 165).
Important
When you deploy a change to this configuration parameter, the AWS IoT Greengrass Core
software restarts for the change to take effect.
182
AWS IoT Greengrass Developer Guide, Version 2
Configuration
This object contains the following information:
noProxyAddresses
(Optional) A comma-separated list of IP addresses or hostnames that are exempt from the
proxy.
proxy
The proxy to which to connect. This object contains the following information:
url
The URL of the proxy server in the format scheme://userinfo@host:port.
• scheme – The scheme, which must be http or https.
Important
Greengrass core devices must run Greengrass nucleus (p. 181) v2.5.0 or later to
use HTTPS proxies.
If you configure an HTTPS proxy, you must add the proxy server CA certificate to
the core device's Amazon root CA certificate. For more information, see Enable
the core device to trust an HTTPS proxy (p. 168).
• userinfo – (Optional) The user name and password information. If you specify this
information in the url, the Greengrass core device ignores the username and password
fields.
• host – The host name or IP address of the proxy server.
• port – (Optional) The port number. If you don't specify the port, then the Greengrass
core device uses the following default values:
• http – 80
• https – 443
Greengrass core devices must run Greengrass nucleus (p. 181) v2.5.0 or later to use
HTTPS proxies.
username
(Optional) The user name that authenticates the proxy server.
password
(Optional) The password that authenticates the proxy server.
mqtt
(Optional) The MQTT configuration for the Greengrass core device. For more information, see
Connect on port 443 or through a network proxy (p. 165).
Important
When you deploy a change to this configuration parameter, the AWS IoT Greengrass Core
software restarts for the change to take effect.
This object contains the following information:
port
(Optional) The port to use for MQTT connections.
Default: 8883
keepAliveTimeoutMs
(Optional) The amount of time in milliseconds between each PING message that the client
sends to keep the MQTT connection alive.
Default: 60000 (60 seconds)
183
AWS IoT Greengrass Developer Guide, Version 2
Configuration
pingTimeoutMs
(Optional) The amount of time in milliseconds that the client waits to receive a PINGACK
message from the server. If the wait exceeds the timeout, the core device closes and reopens the
MQTT connection.
Default: 30000 (30 seconds)
maxInFlightPublishes
(Optional) The maximum number of unacknowledged MQTT QoS 1 messages that can be in
flight at the same time.
This feature is available for v2.1.0 and later of this component.
Default: 5
Valid range: Maximum value of 100
maxMessageSizeInBytes
(Optional) The maximum size of an MQTT message. If a message exceeds this size, the
Greengrass nucleus rejects the message with an error.
This feature is available for v2.1.0 and later of this component.
Default: 131072 (128 KB)
Valid range: Maximum value of 2621440 (2.5 MB)
maxPublishRetry
(Optional) The maximum number of times to retry a message that fails to publish. You can
specify -1 to retry unlimited times.
This feature is available for v2.1.0 and later of this component.
Default: 100
spooler
(Optional) The MQTT spooler configuration for the Greengrass core device. This object contains
the following information:
maxSizeInBytes
(Optional) The maximum size of the cache where the core device stores unprocessed MQTT
messages in memory. If the cache is full, the core device discards the oldest messages to
add new messages.
Default: 2621440 (2.5 MB)
keepQos0WhenOffline
(Optional) You can spool MQTT QoS 0 messages that the core device receives while its
offline. If you set this option to true, the core device spools QoS 0 messages that it
can't send while it's offline. If you set this option to false, the core device discards these
messages. The core device always spools QoS 1 messages unless the spool is full.
Default: false
jvmOptions
(Optional) The JVM options to use to run the AWS IoT Greengrass Core software. For information
about recommended JVM options for running AWS IoT Greengrass Core software, see Control
memory allocation with JVM options (p. 160).
184
AWS IoT Greengrass Developer Guide, Version 2
Configuration
Important
When you deploy a change to this configuration parameter, the AWS IoT Greengrass Core
software restarts for the change to take effect.
iotDataEndpoint
The AWS IoT data endpoint for your AWS account.
When you run the AWS IoT Greengrass Core software with the --provision true option, the
software gets your data and credentials endpoints from AWS IoT and sets them in the nucleus
component.
iotCredEndpoint
The AWS IoT credentials endpoint for your AWS account.
When you run the AWS IoT Greengrass Core software with the --provision true option, the
software gets your data and credentials endpoints from AWS IoT and sets them in the nucleus
component.
greengrassDataPlanePort
This feature is available in v2.0.4 and later of this component.
(Optional) The port to use for data plane connections. For more information, see Connect on port
443 or through a network proxy (p. 165).
Important
You must specify a port where the device can make outbound connections. If you specify a
port that is blocked, the device won't be able to connect to AWS IoT Greengrass to receive
deployments.
Choose from the following options:
• 443
• 8443
Default: 8443
awsRegion
The AWS Region to use.
runWithDefault
The system user to use to run components.
Important
When you deploy a change to this configuration parameter, the AWS IoT Greengrass Core
software restarts for the change to take effect.
This object contains the following information:
posixUser
The name or ID of the system user and, optionally, system group that the core device uses to
run generic and Lambda components. Specify the user and group separated by a colon (:) in
the following format: user:group. The group is optional. If you don't specify a group, the AWS
IoT Greengrass Core software uses the primary group for the user. For example, you can specify
ggc_user or ggc_user:ggc_group. For more information, see Configure the user that runs
components (p. 161).
When you run the AWS IoT Greengrass Core software installer with the --component-
default-user ggc_user:ggc_group option, the software sets this parameter in the nucleus
component.
185
AWS IoT Greengrass Developer Guide, Version 2
Configuration
windowsUser
This feature is available in v2.5.0 and later of this component.
The name of the Windows user to use to run this component on Windows core devices. The
user must exist on each Windows core device, and its name and password must be stored in the
LocalSystem account's Credentials Manager instance. For more information, see Configure the
user that runs components (p. 161).
When you run the AWS IoT Greengrass Core software installer with the --component-
default-user ggc_user option, the software sets this parameter in the nucleus component.
systemResourceLimits
This feature is available in v2.4.0 and later of this component. AWS IoT Greengrass doesn't
currently support this feature on Windows core devices.
The system resource limits to apply to generic and non-containerized Lambda component
processes by default. You can override system resource limits for individual components when
you create a deployment. For more information, see Configure system resource limits for
components (p. 164).
This object contains the following information:
cpus
The maximum amount of CPU time that each component's processes can use on the core
device. A core device's total CPU time is equivalent to the device's number of CPU cores.
For example, on a core device with 4 CPU cores, you can set this value to 2 to limit each
component's processes to 50 percent usage of each CPU core. On a device with 1 CPU core,
you can set this value to 0.25 to limit each component's processes to 25 percent usage of
the CPU. If you set this value to a number greater than the number of CPU cores, the AWS
IoT Greengrass Core software doesn't limit the components' CPU usage.
memory
The maximum amount of RAM (in kilobytes) that each component's processes can use on
the core device.
logging
(Optional) The logging configuration for the core device. For more information about how to
configure and use Greengrass logs, see Monitor AWS IoT Greengrass logs (p. 506).
This object contains the following information:
level
(Optional) The minimum level of log messages to output.
Choose from the following log levels, listed here in level order:
• DEBUG
• INFO
• WARN
• ERROR
Default: INFO
format
(Optional) The data format of the logs. Choose from the following options:
• TEXT – Choose this option if you want to view logs in text form.
• JSON – Choose this option if you want to view logs with the Greengrass CLI logs
command (p. 436) or interact with logs programmatically.
186
AWS IoT Greengrass Developer Guide, Version 2
Configuration
Default: TEXT
outputType
(Optional) The output type for logs. Choose from the following options:
• FILE – The AWS IoT Greengrass Core software outputs logs to files in the directory that you
specify in outputDirectory.
• CONSOLE – The AWS IoT Greengrass Core software prints logs to stdout. Choose this option
to view logs as the core device prints them.
Default: FILE
fileSizeKB
(Optional) The maximum size of each log file (in kilobytes). After a log file exceeds this
maximum file size, the AWS IoT Greengrass Core software creates a new log file.
This parameter applies only when you specify FILE for outputType.
Default: 1024
totalLogsSizeKB
(Optional) The maximum total size of log files (in kilobytes) for each component, including
the Greengrass nucleus. The Greengrass nucleus' log files also include logs from plugin
components (p. 441). After a component's total size of log files exceeds this maximum size, the
AWS IoT Greengrass Core software deletes that component's oldest log files.
This parameter is equivalent to the log manager component's (p. 273) disk space
limit (p. 277) parameter (diskSpaceLimit), which you can specify for the Greengrass nucleus
(system) and each component. The AWS IoT Greengrass Core software uses the minimum of the
two values as the maximum total log size for the Greengrass nucleus and each component.
This parameter applies only when you specify FILE for outputType.
Default: 10240
outputDirectory
(Optional) The output directory for log files.
This parameter applies only when you specify FILE for outputType.
Default: /greengrass/v2/logs, where /greengrass/v2 is the AWS IoT Greengrass root
folder.
fleetstatus
This parameter is available in v2.1.0 and later of this component.
(Optional) The fleet status configuration for the core device.
This object contains the following information:
periodicStatusPublishIntervalSeconds
(Optional) The amount of time (in seconds) between which the core device publishes device
status to the AWS Cloud.
Minimum: 86400
Default: 86400
telemetry
(Optional) The system health telemetry configuration for the core device. For more information
about telemetry metrics and how to act on telemetry data, see Gather system health telemetry data
from AWS IoT Greengrass core devices (p. 515).
187
AWS IoT Greengrass Developer Guide, Version 2
Configuration
This object contains the following information:
enabled
(Optional) You can enable or disable telemetry.
Default: true
periodicAggregateMetricsIntervalSeconds
(Optional) The interval (in seconds) over which the core device aggregates metrics.
If you set this value lower than the minimum supported value, the nucleus uses the default
value instead.
Minimum: 3600
Default: 3600
periodicPublishMetricsIntervalSeconds
(Optional) The amount of time (in seconds) between which the core device publishes telemetry
metrics to the AWS Cloud.
If you set this value lower than the minimum supported value, the nucleus uses the default
value instead.
Minimum: 86400
Default: 86400
deploymentPollingFrequencySeconds
(Optional) The period in seconds at which to poll for deployment notifications.
Default: 15
componentStoreMaxSizeBytes
(Optional) The maximum size on disk of the component store, which comprises component recipes
and artifacts.
Default: 10000000000 (10 GB)
platformOverride
(Optional) A dictionary of attributes that identify the core device's platform. Use this to define
custom platform attributes that component recipes can use to identify the correct lifecycle and
artifacts for the component. For example, you might define a hardware capability attribute to
deploy only the minimal set of artifacts for a component to run. For more information, see the
manifest platform parameter (p. 475) in the component recipe.
You can also use this parameter to override the os and architecture platform attributes of the
core device.
httpClient
This parameter is available in v2.5.0 and later of this component.
(Optional) The HTTP client configuration for the core device. These configuration options apply to all
HTTP requests made by this component. If a core device runs on a slower network, you can increase
these timeout durations to prevent HTTP requests from timing out.
This object contains the following information:
connectionTimeoutMs
(Optional) The amount of time (in milliseconds) to wait for a connection to open before the
connection request times out.
188
AWS IoT Greengrass Developer Guide, Version 2
Local log file
Default: 2000 (2 seconds)
socketTimeoutMs
(Optional) The amount of time (in milliseconds) to wait for data to transfer over an open
connection before the connection times out.
Default: 30000 (30 seconds)
Example Example: Configuration merge update
{
"iotRoleAlias": "GreengrassCoreTokenExchangeRoleAlias",
"networkProxy": {
"noProxyAddresses": "http://192.168.0.1,www.example.com",
"proxy": {
"url": "http://my-proxy-server:1100",
"username": "Mary_Major",
"password": "pass@word1357"
}
},
"mqtt": {
"port": 443
},
"greengrassDataPlanePort": 443,
"jvmOptions": "-Xmx64m",
"runWithDefault": {
"posixUser": "ggc_user:ggc_group"
}
}
Local log file
This component uses the following log file.
Linux
/greengrass/v2/logs/greengrass.log
Windows
C:\greengrass\v2\logs\greengrass.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
Linux
sudo tail -f /greengrass/v2/logs/greengrass.log
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
189
AWS IoT Greengrass Developer Guide, Version 2
Changelog
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.5.2 Bug fixes and improvements
• Fixes an issue where after the Greengrass nucleus updates, the Windows
service fails to start again after you stop it or reboot the device.
2.5.1 Bug fixes and improvements
• Adds support for 32-bit versions of the Java Runtime Environment (JRE) on
Windows.
• Changes thing group removal behavior for core
devices whose AWS IoT policy doesn't grant the
greengrass:ListThingGroupsForCoreDevice permission. With
this version, the deployment continues, logs a warning, and doesn't
remove components when you remove the core device from a thing group.
For more information, see Deploy AWS IoT Greengrass components to
devices (p. 491).
• Fixes an issue with system environment variables that the Greengrass
nucleus makes available to Greengrass component processes. You can now
restart a component for it to use the latest system environment variables.
This version is no longer available.
2.5.0 New features
• Adds support for core devices that run Windows.
• Change the behavior of thing group removal. With this version, you can
remove a core device from a thing group to uninstall that thing group's
components in the next deployment.
As a result of this change, a core device's AWS IoT policy must have
the greengrass:ListThingGroupsForCoreDevice permission. If
you used the AWS IoT Greengrass Core software installer to provision
resources (p. 69), the default AWS IoT policy allows greengrass:*, which
includes this permission. For more information, see Device authentication
and authorization for AWS IoT Greengrass (p. 773).
• Adds support for HTTPS proxy configurations. For more information, see
Connect on port 443 or through a network proxy (p. 165).
• Adds the new windowsUser configuration parameter. You can use this
parameter to specify the default user to use to run components on a
Windows core device. For more information, see Configure the user that
runs components (p. 161).
• Adds the new httpClient configuration options that you can use to
customize HTTP request timeouts to improve performance on slow
networks. For more information, see the httpClient (p. 188) configuration
parameter.
Bug fixes and improvements
• Fixes the bootstrap lifecycle option to restart the core device from a
component.
• Adds support for hyphens in recipe variables.
• Fixes IPC authorization for on-demand Lambda function components.
190
AWS IoT Greengrass Developer Guide, Version 2
Changelog
Version Changes
• Improves log messages and changes non-critical logs from INFO to DEBUG
level, so logs are more useful.
• Removes the iot:DescribeCertificate permission from the default
token exchange role (p. 790) that the Greengrass nucleus creates
when you install the AWS IoT Greengrass Core software with automatic
provisioning (p. 69). This permission isn't used by the Greengrass nucleus.
• Fixes an issue so that the automatic provisioning script doesn't require the
iam:GetPolicy permission if iam:CreatePolicy is available for the
same policy.
• Additional minor fixes and improvements.
2.4.0 New features
• Adds support for system resource limits. You can configure the maximum
amount of CPU and RAM usage that each component's processes can use
on the core device. For more information, see Configure system resource
limits for components (p. 164).
• Adds IPC operations to pause and resume components.
For more information, see PauseComponent (p. 605) and
ResumeComponent (p. 605).
• Adds support for provisioning plugins. You can specify a JAR file to run
during installation to provision required AWS resources for a Greengrass
core device. The Greengrass nucleus includes an interface that you can
implement to develop custom provisioning plugins. For more information,
see Install AWS IoT Greengrass Core software with custom resource
provisioning (p. 117).
• Adds the optional thing-name-policy argument to the AWS IoT
Greengrass Core software installer. You can use this option to specify an
existing or custom AWS IoT policy when you install the AWS IoT Greengrass
Core software with automatic resource provisioning (p. 69).
Bug fixes and improvements
• Updates logging configuration on startup. This fixes an issue where the
logging configuration wasn't applied on startup.
• Updates the nucleus loader symlink to point to the component store in
the Greengrass root folder during installation. This update enables you to
delete the JAR file and other nucleus artifacts that you download when you
install the AWS IoT Greengrass Core software.
• Additional minor fixes and improvements. For more information, see the
changelog on GitHub.
191
AWS IoT Greengrass Developer Guide, Version 2
Changelog
Version Changes
2.3.0 New features
• Adds support for deployment configuration documents up to 10 MB, up
from 7 KB (for deployments that target things) or 31 KB (for deployments
that target thing groups).
To use this feature, a core device's AWS IoT policy must allow the
greengrass:GetDeploymentConfiguration permission. If you
used the AWS IoT Greengrass Core software installer to provision
resources (p. 69), your core device's AWS IoT policy allows greengrass:*,
which includes this permission. For more information, see Device
authentication and authorization for AWS IoT Greengrass (p. 773).
• Adds the iot:thingName recipe variable. You can use this recipe variable
to get the name of the core device's AWS IoT thing in a recipe. For more
information, see Recipe variables (p. 484).
Bug fixes and improvements
• Additional minor fixes and improvements. For more information, see the
changelog on GitHub.
2.2.0 New features
• Adds IPC operations for local shadow management.
Bug fixes and improvements
• Reduces the size of the JAR file.
• Reduces memory usage.
• Fixes issues where the log configuration wasn't updated in certain cases.
• Additional minor fixes and improvements. For more information, see the
changelog on GitHub.
192
AWS IoT Greengrass Developer Guide, Version 2
Changelog
Version Changes
2.1.0 New features
• Supports downloading Docker images from private repositories in Amazon
ECR.
• Adds the following parameters to customize the MQTT configuration on
core devices:
• maxInFlightPublishes – The maximum number of unacknowledged
MQTT QoS 1 messages that can be in flight at the same time.
• maxPublishRetry – The maximum number of times to retry a message
that fails to publish.
• Adds the fleetstatusservice configuration parameter to configure the
interval at which the core device publishes device status to the AWS Cloud.
• Additional minor fixes and improvements. For more information, see the
changelog on GitHub.
Bug fixes and improvements
• Fixes an issue that caused shadow deployments to be duplicated when the
nucleus restarts.
• Fixes an issue that caused the nucleus to crash when it encountered a
service load exception.
• Improves component dependency resolution to fail a deployment that
includes a circular dependency.
• Fixes an issue that prevented a plugin component from being redeployed if
that component had been previously removed from the core device.
• Fix an issue that caused the HOME environment variable to be set to
the /greengrass/v2/work directory for Lambda components or for
components that run as root. The HOME variable is now correctly set to the
home directory for the user that runs the component.
• Additional minor fixes and improvements. For more information, see the
changelog on GitHub.
2.0.5 Bug fixes and improvements
• Correctly routes traffic through a configured network proxy when
downloading AWS-provided components.
• Use the correct Greengrass data plane endpoint in AWS China Regions.
193
AWS IoT Greengrass Developer Guide, Version 2
Client device auth
Version Changes
2.0.4 New features
• Enables HTTPS traffic over port 443. You can use the new
greengrassDataPlanePort configuration parameter for version 2.0.4
of the nucleus component to configure HTTPS communication to travel
over port 443 instead of the default port 8443. For more information, see
Configure HTTPS over port 443 (p. 167).
• Adds the work path recipe variable. You can use this recipe variable to get
the path to components' work folders, which you can use to share files
between components and their dependencies. For more information, see
the work path recipe variable (p. 485).
Bug fixes and improvements
• Prevents the creation of the token exchange AWS Identity and Access
Management (IAM) role policy if a role policy already exists.
As a result of this change, the installer now requires the iam:GetPolicy
and sts:GetCallerIdentity when run with --provision true.
For more information, see Minimal IAM policy for installer to provision
resources (p. 793).
• Correctly handles the cancellation of a deployment that has not yet been
registered successfully.
• Updates the configuration to remove older entries with newer timestamps
when rolling back a deployment.
• Additional minor fixes and improvements. For more information, see the
changelog on GitHub.
2.0.3 Initial version.
Client device auth
The client device auth component (aws.greengrass.clientdevices.Auth) authenticates client
devices and authorizes client device actions.
Note
Client devices are local IoT devices that connect to a Greengrass core device to send
MQTT messages and data to process. For more information, see Interact with local IoT
devices (p. 638).
Topics
• Versions (p. 195)
• Type (p. 195)
• Operating system (p. 195)
• Requirements (p. 195)
• Dependencies (p. 196)
• Configuration (p. 197)
• Local log file (p. 200)
• Changelog (p. 201)
194
AWS IoT Greengrass Developer Guide, Version 2
Versions
Versions
This component has the following versions:
• 2.0.x
Type
This component is a plugin component (aws.greengrass.plugin). The Greengrass nucleus (p. 181)
runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when
you change this component's version on the core device.
This component uses the same log file as the Greengrass nucleus. For more information, see Monitor
AWS IoT Greengrass logs (p. 506).
For more information, see Component types (p. 441).
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
Requirements
This component has the following requirements:
• The Greengrass service role (p. 796) must be associated to your AWS account and allow the
iot:DescribeCertificate permission.
• The core device's AWS IoT policy must allow the following permissions:
• greengrass:PutCertificateAuthorities
• greengrass:VerifyClientDeviceIdentity
• greengrass:VerifyClientDeviceIoTCertificateAssociation
• greengrass:GetConnectivityInfo
For more information, see AWS IoT policies for data plane operations (p. 774) and Minimal AWS IoT
policy to support client devices (p. 779).
Endpoints and ports
This component must be able to perform outbound requests to the following endpoints and ports, in
addition to endpoints and ports required for basic operation. For more information, see Allow device
traffic through a proxy or firewall (p. 807).
Endpoint Port Required Description
iot.region.amazonaws.com 443 Yes Used to get
information
195
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
Endpoint Port Required Description
about AWS
IoT thing
certificates.
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 201) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.0.4
The following table lists the dependencies for version 2.0.4 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.2.0 <2.6.0 Soft
2.0.3 and 2.0.2
The following table lists the dependencies for versions 2.0.3 and 2.0.2 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.2.0 <2.5.0 Soft
2.0.1
The following table lists the dependencies for version 2.0.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.2.0 <2.4.0 Soft
2.0.0
The following table lists the dependencies for version 2.0.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.2.0 <2.3.0 Soft
For more information about component dependencies, see the component recipe reference (p. 473).
196
AWS IoT Greengrass Developer Guide, Version 2
Configuration
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
deviceGroups
Device groups are groups of client devices that have permissions to connect and communicate with a
core device. Use selection rules to identify groups of client devices, and define authorization policies
that specify the permissions for each device group.
This object contains the following information:
formatVersion
The format version for this configuration object.
Choose from the following options:
• 2021-03-05
definitions
The device groups for this core device. Each definition specifies a selection rule to evaluate if a
client device is a member of the group. Each definition also specifies the permissions policy to
apply to client devices who match the selection rule. If a client device is a member of multiple
device groups, the device's permissions are the union of each group's permissions policy.
This object contains the following information:
groupNameKey
The name of this device group. Replace groupNameKey with a name that helps you identify
this device group.
This object contains the following information:
selectionRule
The selection rule that specifies which client devices are members of this device group.
When a client device connects, the core device evaluates the selection rule to determine
if the client device is a member of this device group. If the client device is a member,
the core device uses this device group's policy to authorize the client device's actions.
Use the * wildcard to match multiple client devices with one selection rule clause. You
can use this wildcard at the end of the thing name to match client devices whose names
start with a string that you specify. You can also use this wildcard to match all client
devices.
Note
To select a value that contains a colon character (:), escape the colon with a
backslash character (\). In formats such as JSON, you must escape backslash
characters, so you enter two backslash characters before the colon character.
For example, specify thingName: MyTeam\\:ClientDevice1 to select a
thing whose name is MyTeam:ClientDevice1.
You can specify the following selector:
• thingName – The name of a client device's AWS IoT thing.
Example Example selection rule
The following selection rule matches client devices whose names are
MyClientDevice1 or MyClientDevice2.
197
AWS IoT Greengrass Developer Guide, Version 2
Configuration
thingName: MyClientDevice1 OR thingName: MyClientDevice2
Example Example selection rule (use wildcards)
The following selection rule matches client devices whose names start with
MyClientDevice.
thingName: MyClientDevice*
Example Example selection rule (match all devices)
The following selection rule matches all client devices.
thingName: *
policyName
The permissions policy that applies to client devices in this device group. Specify the
name of a policy that you define in the policies object.
policies
The device group authorization policies for client devices that connect to the core device. Each
authorization policy specifies a set of actions and the resources on which a client device can
perform those actions.
This object contains the following information:
policyNameKey
The name of this authorization policy. Replace policyNameKey with a name that helps you
identify this authorization policy. You use this policy name to define which policy applies to
a device group.
This object contains the following information:
statementNameKey
The name of this policy statement. Replace statementNameKey with a name that
helps you identify this policy statement.
This object contains the following information:
operations
The list of operations to allow for the resources in this policy.
You can include any of the following operations:
• mqtt:connect – Grants permission to connect to the core device. Client devices
must have this permission to connect to a core device.
This operation supports the following resources:
• mqtt:clientId:deviceClientId – Restrict access based on the client ID
that a client device uses to connect to the core device's MQTT broker. Replace
deviceClientId with the client ID to use.
• mqtt:publish – Grants permission to publish MQTT messages to topics.
This operation supports the following resources:
• mqtt:topic:mqttTopic – Restrict access based on the MQTT topic where a
client device publishes a message. Replace mqttTopic with the topic to use.
198
AWS IoT Greengrass Developer Guide, Version 2
Configuration
This resource doesn't support MQTT topic wildcards.
• mqtt:subscribe – Grants permission to subscribe to MQTT topic filters to
receive messages.
This operation supports the following resources:
• mqtt:topicfilter:mqttTopicFilter – Restrict access based on the
MQTT topics where a client device can subscribe to messages. Replace
mqttTopicFilter with the topic filter to use.
This resource supports the + and # MQTT topic wildcards. For more
information, see MQTT topics in the AWS IoT Core Developer Guide.
The client device can subscribe to the exact topic filters that you
allow. For example, if you allow the client device to subscribe to the
mqtt:topicfilter:client/+/status resource, the client device can
subscribe to client/+/status but not client/client1/status.
You can specify the * wildcard to allow access to all actions.
resources
The list of resources to allow for the operations in this policy. Specify resources that
correspond to the operations in this policy. For example, you might specify a list
of MQTT topic resources (mqtt:topic:mqttTopic) in a policy that specifies the
mqtt:publish operation.
You can specify the * wildcard to allow access to all resources. You can't
use the * wildcard to match partial resource identifiers. For example, you
can specify "resources": "*", but you can't specify "resources":
"mqtt:clientId:*".
statementDescription
(Optional) A description for this policy statement.
Example Example: Configuration merge update (using a restrictive policy)
The following example configuration specifies to allow client devices whose names start with
MyClientDevice to connect and publish/subscribe on all topics.
{
"deviceGroups": {
"formatVersion": "2021-03-05",
"definitions": {
"MyDeviceGroup": {
"selectionRule": "thingName: MyClientDevice*",
"policyName": "MyRestrictivePolicy"
}
},
"policies": {
"MyRestrictivePolicy": {
"AllowConnect": {
"statementDescription": "Allow client devices to connect.",
"operations": [
"mqtt:connect"
],
"resources": [
"*"
]
},
199
AWS IoT Greengrass Developer Guide, Version 2
Local log file
"AllowPublish": {
"statementDescription": "Allow client devices to publish on test/topic.",
"operations": [
"mqtt:publish"
],
"resources": [
"mqtt:topic:test/topic"
]
},
"AllowSubscribe": {
"statementDescription": "Allow client devices to subscribe to test/topic/
response.",
"operations": [
"mqtt:subscribe"
],
"resources": [
"mqtt:topicfilter:test/topic/response"
]
}
}
}
}
}
Example Example: Configuration merge update (using a permissive policy)
The following example configuration specifies to allow client devices whose names start with
MyClientDevice to connect and publish/subscribe on all topics.
{
"deviceGroups": {
"formatVersion": "2021-03-05",
"definitions": {
"MyDeviceGroup": {
"selectionRule": "thingName: MyClientDevice*",
"policyName": "MyPermissivePolicy"
}
},
"policies": {
"MyPermissivePolicy": {
"AllowAll": {
"statementDescription": "Allow client devices to perform all actions.",
"operations": [
"*"
],
"resources": [
"*"
]
}
}
}
}
}
Local log file
This component uses the same log file as the Greengrass nucleus (p. 181) component.
Linux
/greengrass/v2/logs/greengrass.log
200
AWS IoT Greengrass Developer Guide, Version 2
Changelog
Windows
C:\greengrass\v2\logs\greengrass.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
Linux
sudo tail -f /greengrass/v2/logs/greengrass.log
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.0.4 Version updated for Greengrass nucleus version 2.5.0 release.
2.0.3 Bug fixes and improvements
• Credentials now refresh if you rotate the core device's private key.
• Updates to make log messages more clear.
2.0.2 Version updated for Greengrass nucleus version 2.4.0 release.
2.0.1 Version updated for Greengrass nucleus version 2.3.0 release.
2.0.0 Initial version.
CloudWatch metrics
The Amazon CloudWatch metrics component (aws.greengrass.Cloudwatch) publishes custom
metrics from Greengrass core devices to Amazon CloudWatch. The component enables components to
publish CloudWatch metrics, which you can use to monitor and analyze the Greengrass core device's
environment. For more information, see Using Amazon CloudWatch metrics in the Amazon CloudWatch
User Guide.
To publish a CloudWatch metric with this component, publish a message to a topic where this
component subscribes. By default, this component subscribes to the cloudwatch/metric/put local
publish/subscribe (p. 561) topic. You can specify other topics, including AWS IoT Core MQTT topics,
when you deploy this component.
This component batches metrics that are in the same namespace and publishes them to CloudWatch at
regular intervals.
201
AWS IoT Greengrass Developer Guide, Version 2
Versions
Note
This component provides similar functionality to the CloudWatch metrics connector in AWS
IoT Greengrass V1. For more information, see CloudWatch metrics connector in the AWS IoT
Greengrass V1 Developer Guide.
Topics
• Versions (p. 202)
• Type (p. 202)
• Operating system (p. 202)
• Requirements (p. 203)
• Dependencies (p. 205)
• Configuration (p. 207)
• Input data (p. 211)
• Output data (p. 213)
• Licenses (p. 214)
• Local log file (p. 214)
• Changelog (p. 215)
• See also (p. 215)
Versions
This component has the following versions:
• 3.0.x
• 2.0.x
For information about changes in each version of the component, see the changelog (p. 215).
Type
3.0.x
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
2.0.x
This component is a Lambda component (aws.greengrass.lambda). The Greengrass
nucleus (p. 181) runs this component's Lambda function using the Lambda launcher
component (p. 252).
For more information, see Component types (p. 441).
Operating system
3.0.x
This component can be installed on core devices that run the following operating systems:
• Linux
202
AWS IoT Greengrass Developer Guide, Version 2
Requirements
• Windows
2.0.x
This component can be installed on Linux core devices only.
Requirements
This component has the following requirements:
3.0.x
• Python version 3.7 installed on the core device and added to the PATH environment variable.
• The Greengrass device role (p. 790) must allow the cloudwatch:PutMetricData action, as
shown in the following example IAM policy.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"cloudwatch:PutMetricData"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
For more information, see Amazon CloudWatch permissions reference in the Amazon CloudWatch
User Guide.
2.0.x
• Your core device must meet the requirements to run Lambda functions. If you want the core
device to run containerized Lambda functions, the device must meet the requirements to do so.
For more information, see Lambda function requirements (p. 64).
• Python version 3.7 installed on the core device and added to the PATH environment variable.
• The Greengrass device role (p. 790) must allow the cloudwatch:PutMetricData action, as
shown in the following example IAM policy.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"cloudwatch:PutMetricData"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
For more information, see Amazon CloudWatch permissions reference in the Amazon CloudWatch
User Guide.
203
AWS IoT Greengrass Developer Guide, Version 2
Requirements
• To receive output data from this component, you must merge the following configuration update
for the legacy subscription router component (p. 260) when you deploy this component. The
legacy subscription router component (aws.greengrass.LegacySubscriptionRouter) is
a dependency of this component. This configuration specifies the topic where this component
publishes responses.
Legacy subscription router v2.1.x
{
"subscriptions": {
"aws-greengrass-cloudwatch": {
"id": "aws-greengrass-cloudwatch",
"source": "component:aws.greengrass.Cloudwatch",
"subject": "cloudwatch/metric/put/status",
"target": "cloud"
}
}
}
Legacy subscription router v2.0.x
{
"subscriptions": {
"aws-greengrass-cloudwatch": {
"id": "aws-greengrass-cloudwatch",
"source": "arn:aws:lambda:region:aws:function:aws-greengrass-
cloudwatch:version",
"subject": "cloudwatch/metric/put/status",
"target": "cloud"
}
}
}
• Replace region with the AWS Region that you use.
• Replace version with the version of the Lambda function that this component runs.
To find the Lambda function version, you must view the recipe for the version of this
component that you want to deploy. Open this component's details page in the AWS IoT
Greengrass console, and look for the Lambda function key-value pair. This key-value pair
contains the name and version of the Lambda function.
Important
You must update the Lambda function version on the legacy subscription router
every time you deploy this component. This ensures that you use the correct Lambda
function version for the component version that you deploy.
For more information, see Create deployments (p. 493).
Endpoints and ports
This component must be able to perform outbound requests to the following endpoints and ports, in
addition to endpoints and ports required for basic operation. For more information, see Allow device
traffic through a proxy or firewall (p. 807).
Endpoint Port Required Description
monitoring.region.amazonaws.com 443 Yes Upload
CloudWatch
metrics.
204
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 215) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
3.0.0
The following table lists the dependencies for version 3.0.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <3.0.0 Soft
Token exchange >=0.0.0 Hard
service (p. 407)
2.0.8
The following table lists the dependencies for version 2.0.8 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.6.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.7
The following table lists the dependencies for version 2.0.7 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.6
The following table lists the dependencies for version 2.0.6 of this component.
205
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.5
The following table lists the dependencies for version 2.0.5 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.4
The following table lists the dependencies for version 2.0.4 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.2.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.3
The following table lists the dependencies for version 2.0.3 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.3 <2.1.0 Hard
Lambda launcher (p. 252) >=1.0.0 Hard
Lambda runtimes (p. 258) >=1.0.0 Soft
Token exchange >=1.0.0 Hard
service (p. 407)
206
AWS IoT Greengrass Developer Guide, Version 2
Configuration
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
3.0.x
PublishInterval
(Optional) The maximum number of seconds to wait before the component publishes batched
metrics for a given namespace. To configure the component to publish metrics as it receives
them, which means without batching, specify 0.
The component publishes to CloudWatch after it receives 20 metrics in the same namespace or
after the interval that you specify.
Note
The component doesn't specify the order in which events publish.
This value can be a maximum of 900 seconds.
Default: 10 seconds
MaxMetricsToRetain
(Optional) The maximum number of metrics across all namespaces to save in memory before
the component replaces them with newer metrics.
This limit applies when the core device doesn't have a connection to the internet, so the
component buffers the metrics to publish later. When the buffer is full, the component replaces
the oldest metrics with newer ones. Metrics in a given namespace replace only metrics in the
same namespace.
Note
If the host process for the component is interrupted, the component doesn't save
metrics. This can happen during a deployment or when the core device restarts, for
example.
This value must be at least 2,000 metrics.
Default: 5,000 metrics
InputTopic
(Optional) The topic to which the component subscribes to receive messages. If you specify
true for PubSubToIoTCore, you can use MQTT wildcards (+ and #) in this topic.
Default: cloudwatch/metric/put
OutputTopic
(Optional) The topic to which the component publishes status responses. If you specify true for
PubSubToIoTCore, you can use MQTT wildcards (+ and #) in this topic.
Default: cloudwatch/metric/put/status
PubSubToIoTCore
(Optional) String value that defines whether to publish and subscribe to AWS IoT Core MQTT
topics. Supported values are true and false.
207
AWS IoT Greengrass Developer Guide, Version 2
Configuration
Default: false
UseInstaller
(Optional) Boolean value that defines whether to use the installer script in this component to
install this component's SDK dependencies.
Set this value to false if you want to use a custom script to install dependencies, or if you want
to include runtime dependencies in a pre-built Linux image. To use this component, you will
need to install the following libraries, including any dependencies, and make them available to
the default Greengrass system user.
• AWS IoT Device SDK v2 for Python
• AWS SDK for Python (Boto3)
Default: true
PublishRegion
(Optional) The AWS Region to which to publish CloudWatch metrics. This value overrides the
default Region for the core device. This parameter is required only for cross-Region metrics.
accessControl
(Optional) The object that contains the authorization policy (p. 552) that allows the
component to publish and subscribe to the specified topics. If you specify custom values for
InputTopic and OutputTopic, you must update the resource values in this object.
Default:
{
"aws.greengrass.ipc.pubsub": {
"aws.greengrass.Cloudwatch:pubsub:1": {
"policyDescription": "Allows access to subscribe to input topics.",
"operations": [
"aws.greengrass#SubscribeToTopic"
],
"resources": [
"cloudwatch/metric/put"
]
},
"aws.greengrass.Cloudwatch:pubsub:2": {
"policyDescription": "Allows access to publish to output topics.",
"operations": [
"aws.greengrass#PublishToTopic"
],
"resources": [
"cloudwatch/metric/put/status"
]
}
},
"aws.greengrass.ipc.mqttproxy": {
"aws.greengrass.Cloudwatch:mqttproxy:1": {
"policyDescription": "Allows access to subscribe to input topics.",
"operations": [
"aws.greengrass#SubscribeToIoTCore"
],
"resources": [
"cloudwatch/metric/put"
]
},
"aws.greengrass.Cloudwatch:mqttproxy:2": {
"policyDescription": "Allows access to publish to output topics.",
"operations": [
"aws.greengrass#PublishToIoTCore"
208
AWS IoT Greengrass Developer Guide, Version 2
Configuration
],
"resources": [
"cloudwatch/metric/put/status"
]
}
}
}
Example Example: Configuration merge update
{
"PublishInterval": 0,
"PubSubToIoTCore": true
}
2.0.x
Note
This component's default configuration includes Lambda function parameters. We
recommend that you edit only the following parameters to configure this component on
your devices.
lambdaParams
An object that contains the parameters for this component's Lambda function. This object
contains the following information:
EnvironmentVariables
An object that contains the Lambda function's parameters. This object contains the
following information:
PUBLISH_INTERVAL
(Optional) The maximum number of seconds to wait before the component publishes
batched metrics for a given namespace. To configure the component to publish metrics
as it receives them, which means without batching, specify 0.
The component publishes to CloudWatch after it receives 20 metrics in the same
namespace or after the interval that you specify.
Note
The component doesn't guarantee the order in which events publish.
This value can be at most 900 seconds.
Default: 10 seconds
MAX_METRICS_TO_RETAIN
(Optional) The maximum number of metrics across all namespaces to save in memory
before the component replaces them with newer metrics.
This limit applies when the core device doesn't have a connection to the internet, so the
component buffers the metrics to publish later. When the buffer is full, the component
replaces the oldest metrics with newer ones. Metrics in a given namespace replace only
metrics in the same namespace.
Note
If the host process for the component is interrupted, the component doesn't
save metrics. This can happen during a deployment or when the core device
restarts, for example.
209
AWS IoT Greengrass Developer Guide, Version 2
Configuration
This value must be at least 2,000 metrics.
Default: 5,000 metrics
PUBLISH_REGION
(Optional) The AWS Region to which to publish CloudWatch metrics. This value
overrides the default Region for the core device. This parameter is required only for
cross-Region metrics.
containerMode
(Optional) The containerization mode for this component. Choose from the following options:
• NoContainer – The component doesn't run in an isolated runtime environment.
• GreengrassContainer – The component runs in an isolated runtime environment inside the
AWS IoT Greengrass container.
Default: GreengrassContainer
containerParams
(Optional) An object that contains the container parameters for this component. The component
uses these parameters if you specify GreengrassContainer for containerMode.
This object contains the following information:
memorySize
(Optional) The amount of memory (in kilobytes) to allocate to the component.
Defaults to 64 MB (65,535 KB).
pubsubTopics
(Optional) An object that contains the topics where the component subscribes to receive
messages. You can specify each topic and whether the component subscribes to MQTT topics
from AWS IoT Core or local publish/subscribe topics.
This object contains the following information:
0 – This is an array index as a string.
An object that contains the following information:
type
(Optional) The type of publish/subscribe messaging that this component uses to
subscribe to messages. Choose from the following options:
• Pubsub – Subscribe to local publish/subscribe messages. If you choose this option,
the topic can't contain MQTT wildcards. For more information about how to send
messages from custom component when you specify this option, see Publish/
subscribe local messages (p. 561).
• IotCore – Subscribe to AWS IoT Core MQTT messages. If you choose this option,
the topic can contain MQTT wildcards. For more information about how to send
messages from custom components when you specify this option, see Publish/
subscribe AWS IoT Core MQTT messages (p. 586).
Default: Pubsub
topic
(Optional) The topic to which the component subscribes to receive messages. If you
specify IotCore for type, you can use MQTT wildcards (+ and #) in this topic.
210
AWS IoT Greengrass Developer Guide, Version 2
Input data
Example Example: Configuration merge update (container mode)
{
"containerMode": "GreengrassContainer"
}
Example Example: Configuration merge update (no container mode)
{
"containerMode": "NoContainer"
}
Input data
This component accepts metrics on the following topic and publishes the metrics to CloudWatch. By
default, this component subscribes to local publish/subscribe messages. For more information about
how to publish messages to this component from your custom components, see Publish/subscribe local
messages (p. 561).
Beginning with component version v3.0.0, you can optionally configure this component to subscribe
to an MQTT topic by setting the PubSubToIoTCore configuration parameter to true. For more
information about publishing messages to an MQTT topic in your custom components, see Publish/
subscribe AWS IoT Core MQTT messages (p. 586).
Default topic: cloudwatch/metric/put
The message accepts the following properties. Input messages must be in JSON format.
request
The metric in this message.
The request object contains the metric data to publish to CloudWatch. The metric values must meet
the specifications of the PutMetricData operation.
Type: object that contains the following information:
namespace
The user-defined namespace for the metric data in this request. CloudWatch uses namespaces
as containers for metric data points.
Note
You can't specify a namespace that begins with the reserved string AWS/.
Type: string
Valid pattern: [^:].*
metricData
The data for the metric.
Type: object that contains the following information:
metricName
The name of the metric.
Type: string
211
AWS IoT Greengrass Developer Guide, Version 2
Input data
value
The value for the metric.
Note
CloudWatch rejects values that are too small or too large. The value must be
between 8.515920e-109 and 1.174271e+108 (Base 10) or 2e-360 and 2e360
(Base 2). CloudWatch doesn't support special values such as NaN, +Infinity, and
-Infinity.
Type: double
dimensions
(Optional) The for the metric. Dimensions provide additional information about the metric
and its data. A metric can define up to 10 dimensions.
Type: array of objects that each contain the following information:
name
(Optional) The dimension name.
Type: string
value
(Optional) The dimension value.
Type: string
timestamp
(Optional) The time at which the metric data was received, expressed in seconds in Unix
epoch time.
Defaults to the time at which the component receives the message.
Type: double
Note
If you use between versions 2.0.3 and 2.0.7 of this component, we recommend
that you retrieve the timestamp separately for each metric when you send multiple
metrics from a single source. Don't use a variable to store the timestamp.
unit
(Optional) The unit of the metric.
Type: string
Valid values: Seconds, Microseconds, Milliseconds, Bytes, Kilobytes, Megabytes,
Gigabytes, Terabytes, Bits, Kilobits, Megabits, Gigabits, Terabits, Percent,
Count, Bytes/Second, Kilobytes/Second, Megabytes/Second, Gigabytes/Second,
Terabytes/Second, Bits/Second, Kilobits/Second, Megabits/Second, Gigabits/
Second, Terabits/Second, Count/Second, None
Defaults to None.
Note
All quotas that apply to the CloudWatch PutMetricData API apply to metrics that you publish
with this component. The following quotas are especially important:
212
AWS IoT Greengrass Developer Guide, Version 2
Output data
• 40 KB limit on the API payload
• 20 metrics per API request
• 150 transactions per second (TPS) for the PutMetricData API
For more information, see CloudWatch service quotas in the CloudWatch User Guide.
Example Example input
{
"request": {
"namespace": "Greengrass",
"metricData": {
"metricName": "latency",
"dimensions": [
{
"name": "hostname",
"value": "test_hostname"
}
],
"timestamp": 1539027324,
"value": 123.0,
"unit": "Seconds"
}
}
}
Output data
This component publishes responses as output data on the following local publish/subscribe topic
by default. For more information about how to subscribe to messages on this topic in your custom
components, see Publish/subscribe local messages (p. 561).
You can optionally configure this component to publish to an MQTT topic by setting the
PubSubToIoTCore configuration parameter to true. For more information about subscribing to
messages on an MQTT topic in your custom components, see Publish/subscribe AWS IoT Core MQTT
messages (p. 586).
Note
Component versions 2.0.x publish responses as output data on an MQTT topic by default. You
must specify the topic as the subject in the configuration for the legacy subscription router
component (p. 260).
Default topic: cloudwatch/metric/put/status
Example Example output: Success
The response includes the namespace of the metric data and the RequestId field from the CloudWatch
response.
{
"response": {
"cloudwatch_rid": "70573243-d723-11e8-b095-75ff2EXAMPLE",
"namespace": "Greengrass",
"status": "success"
}
}
213
AWS IoT Greengrass Developer Guide, Version 2
Licenses
Example Example output: Failure
{
"response" : {
"namespace": "Greengrass",
"error": "InvalidInputException",
"error_message": "cw metric is invalid",
"status": "fail"
}
}
Note
If the component detects an error that can be retried, such as a connection error, it retries the
publish in the next batch.
Licenses
This component includes the following third-party software/licensing:
• AWS SDK for Python (Boto3)/Apache License 2.0
• botocore/Apache License 2.0
• dateutil/PSF License
• docutils/BSD License, GNU General Public License (GPL), Python Software Foundation License, Public
Domain
• jmespath/MIT License
• s3transfer/Apache License 2.0
• urllib3/MIT License
This component is released under the Greengrass Core Software License Agreement.
Local log file
This component uses the following log file.
Linux
/greengrass/v2/logs/aws.greengrass.Cloudwatch.log
Windows
C:\greengrass\v2\logs\aws.greengrass.Cloudwatch.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
Linux
sudo tail -f /greengrass/v2/logs/aws.greengrass.Cloudwatch.log
214
AWS IoT Greengrass Developer Guide, Version 2
Changelog
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\aws.greengrass.Cloudwatch.log -Tail 10 -Wait
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.0.8 Bug fixes and improvements
• Adds support for duplicate timestamps in input data.
• Version updated for Greengrass nucleus version 2.5.0 release.
3.0.0 This version of the CloudWatch metrics component expects different
configuration parameters than version 2.x. If you use a non-default configuration
for version 2.x, and you want to upgrade from v2.x to v3.x, you must update
the component's configuration. For more information, see CloudWatch metrics
component configuration (p. 207).
New features
• Adds support for core devices that run Windows.
• Changes the component type from Lambda component to generic
component. This component now no longer depends on the legacy
subscription router component to create subscriptions.
• Adds new InputTopic configuration parameter to specify the topic to
which the component subscribes to receive messages.
• Adds new OutputTopic configuration parameter to specify the topic to
which the component publishes status responses.
• Adds new PubSubToIoTCore configuration parameter to specify whether
to publish and subscribe to AWS IoT Core MQTT topics.
• Adds the new UseInstaller configuration parameter that lets
you optionally disable the installation script that installs component
dependencies.
Bug fixes and improvements
Adds support for duplicate timestamps in input data.
2.0.7 Version updated for Greengrass nucleus version 2.4.0 release.
2.0.6 Version updated for Greengrass nucleus version 2.3.0 release.
2.0.5 Version updated for Greengrass nucleus version 2.2.0 release.
2.0.4 Version updated for Greengrass nucleus version 2.1.0 release.
2.0.3 Initial version.
See also
• Using Amazon CloudWatch metrics in the Amazon CloudWatch User Guide
215
AWS IoT Greengrass Developer Guide, Version 2
Docker application manager
• PutMetricData in the Amazon CloudWatch API Reference
Docker application manager
The Docker application manager component (aws.greengrass.DockerApplicationManager)
enables AWS IoT Greengrass to download Docker images from public image registries. It also enables
AWS IoT Greengrass to manage credentials to download images from private repositories in Amazon
Elastic Container Registry (Amazon ECR).
When you develop a custom component that runs a Docker container, include the Docker application
manager as a dependency to download the Docker images that are specified as artifacts in your
component. For more information, see Run a Docker container (p. 456).
Topics
• Versions (p. 216)
• Type (p. 216)
• Operating system (p. 216)
• Requirements (p. 216)
• Dependencies (p. 218)
• Configuration (p. 219)
• Local log file (p. 219)
• Changelog (p. 220)
• See also (p. 220)
Versions
This component has the following versions:
• 2.0.x
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
Requirements
This component has the following requirements:
216
AWS IoT Greengrass Developer Guide, Version 2
Requirements
• Docker Engine 1.9.1 or later installed on your Greengrass core device. Version 20.10 is the latest
version that is verified to work with the connector. You must install Docker directly on the core device
before you deploy custom components that run Docker containers.
• The Docker daemon started and running on the core device before you deploy this component.
• Docker images stored in one of the following supported image sources:
• Public and private image repositories in Amazon Elastic Container Registry (Amazon ECR)
• Public Docker Hub repository
• Public Docker Trusted Registry
• Docker images included as artifacts in your custom Docker container components. Use the following
URI formats to specify your Docker images:
• Private Amazon ECR image: docker:account-
id.dkr.ecr.region.amazonaws.com/repository/image[:tag|@digest]
• Public Amazon ECR image: docker:public.ecr.aws/repository/image[:tag|@digest]
• Public Docker Hub image: docker:name[:tag|@digest]
For more information, see Run a Docker container (p. 456).
Note
If you don't specify the image tag or image digest in the artifact URI for an image, then the
Docker application manager pulls the latest available version of that image when you deploy
your custom Docker container component. To ensure that all of your core devices run the
same version of an image, we recommend that you include the image tag or image digest in
the artifact URI.
• The system user that runs a Docker container component must have root or administrator permissions,
or you must configure Docker to run it as a non-root or non-admistrator user. On Linux devices, you
can add a user to the docker group to call docker commands without sudo. On Windows devices,
you can add a user to the docker-users group to call docker commands without adminstrator
privileges.
On Linux, to add ggc_user, or the non-root user that you use to run AWS IoT Greengrass, to the
docker group that you configure, run the following command.
sudo usermod -aG docker user-name
For more information, see the following Docker documentation:
• Linux: Manage Docker as a non-root user
• Windows: Install Docker Desktop on Windows
• If you configure the AWS IoT Greengrass Core software to use a network proxy (p. 165), you must
configure Docker to use the same proxy server.
• If your Docker images are stored in an Amazon ECR private registry, then you must include
the token exchange service component as a dependency in the Docker container component.
Also, the Greengrass device role (p. 790) must allow the ecr:GetAuthorizationToken,
ecr:BatchGetImage, and ecr:GetDownloadUrlForLayer actions, as shown in the following
example IAM policy.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"ecr:GetAuthorizationToken",
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer"
],
"Resource": [
217
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
"*"
],
"Effect": "Allow"
}
]
}
Endpoints and ports
This component must be able to perform outbound requests to the following endpoints and ports, in
addition to endpoints and ports required for basic operation. For more information, see Allow device
traffic through a proxy or firewall (p. 807).
Endpoint Port Required Description
ecr.region.amazonaws.com 443 No Required
if you
download
Docker
images from
Amazon
ECR.
hub.docker.com 443 No Required
if you
registry.hub.docker.com/v1 download
Docker
images from
Docker Hub.
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 220) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.0.4
The following table lists the dependencies for version 2.0.4 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.1.0 <2.6.0 Soft
2.0.3
The following table lists the dependencies for version 2.0.3 of this component.
218
AWS IoT Greengrass Developer Guide, Version 2
Configuration
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.1.0 <2.5.0 Soft
2.0.2
The following table lists the dependencies for version 2.0.2 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.1.0 <2.4.0 Soft
2.0.1
The following table lists the dependencies for version 2.0.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.1.0 <2.3.0 Soft
2.0.0
The following table lists the dependencies for version 2.0.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.1.0 <2.2.0 Soft
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component doesn't have any configuration parameters.
Local log file
This component uses the following log file.
Linux
/greengrass/v2/logs/aws.greengrass.DockerApplicationManager.log
Windows
C:\greengrass\v2\logs\aws.greengrass.DockerApplicationManager.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
219
AWS IoT Greengrass Developer Guide, Version 2
Changelog
Linux
sudo tail -f /greengrass/v2/logs/aws.greengrass.DockerApplicationManager.log
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\aws.greengrass.DockerApplicationManager.log -Tail
10 -Wait
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.0.4 Version updated for Greengrass nucleus version 2.5.0 release.
2.0.3 Version updated for Greengrass nucleus version 2.4.0 release.
2.0.2 Version updated for Greengrass nucleus version 2.3.0 release.
2.0.1 Version updated for Greengrass nucleus version 2.2.0 release.
2.0.0 Initial version.
See also
• Run a Docker container (p. 456)
Edge connector for Kinesis Video Streams
The edge connector for Kinesis Video Streams component (aws.iot.EdgeConnectorForKVS) reads
video feeds from local cameras and publishes the streams to Kinesis Video Streams. You can configure
this component to read video feeds from Internet Protocol (IP) cameras using Real Time Streaming
Protocol (RTSP). Then, you can set up dashboards in Amazon Managed Grafana or local Grafana servers
to monitor and interact with the video streams.
You can integrate this component with AWS IoT TwinMaker to display and control video streams in
Grafana dashboards. AWS IoT TwinMaker is an AWS service that enables you to build operational digital
twins of physical systems. You can use AWS IoT TwinMaker to visualize data from sensors, cameras, and
enterprise applications for you to track your physical factories, buildings, or industrial plants. You can
also use this data to monitor operations, diagnose errors, and repair errors. For more information, see
What is AWS IoT TwinMaker? in the AWS IoT TwinMaker User Guide.
This component stores its configuration in AWS IoT SiteWise, which is an AWS service that models and
stores industrial data. In AWS IoT SiteWise, assets represent objects such as devices, equipment, or
groups of other objects. To configure and use this component, you create an AWS IoT SiteWise asset
for each Greengrass core device and for each IP camera connected to each core device. Each asset has
properties that you configure to control features, such as live streaming, on-demand upload, and local
caching. To specify the URL for each camera, you create a secret in AWS Secrets Manager that contains
the URL of the camera. If the camera requires authentication, you also specify a user name and password
in the URL. Then, you specify that secret in an asset property for the IP camera.
220
AWS IoT Greengrass Developer Guide, Version 2
Versions
This component uploads each camera's video stream to a Kinesis video stream. You specify the name of
the destination Kinesis video stream in the AWS IoT SiteWise asset configuration for each camera. If the
Kinesis video stream doesn't exist, this component creates it for you.
AWS IoT TwinMaker provides a script that you can run to create these AWS IoT SiteWise assets and
Secrets Manager secrets. For more information about how to create these resources, and how to install,
configure, and use this component, see AWS IoT TwinMaker video stream integration in the AWS IoT
TwinMaker User Guide.
Topics
• Versions (p. 221)
• Type (p. 221)
• Operating system (p. 221)
• Requirements (p. 221)
• Dependencies (p. 223)
• Configuration (p. 224)
• Licenses (p. 224)
• Usage (p. 224)
• Local log file (p. 224)
• Changelog (p. 224)
• See also (p. 225)
Versions
This component has the following versions:
• 1.0.x
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
Operating system
This component can be installed on Linux core devices only.
Requirements
This component has the following requirements:
• GStreamer 1.8.4 or later installed on the core device. For more information, see Installing GStreamer.
On a device with apt, you can run the following commands to install GStreamer.
sudo apt install -y libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev gstreamer1.0-
plugins-base-apps
sudo apt install -y gstreamer1.0-libav
sudo apt install -y gstreamer1.0-plugins-bad gstreamer1.0-plugins-good gstreamer1.0-
plugins-ugly gstreamer1.0-tools
221
AWS IoT Greengrass Developer Guide, Version 2
Requirements
• An AWS IoT SiteWise asset for each core device. This AWS IoT SiteWise asset represents the core
device. For more information about how to create this asset, see Create resources for the edge
connector for Kinesis Video Streams in the AWS IoT TwinMaker User Guide.
• An AWS IoT SiteWise asset for each IP camera that you connect to each core device. These AWS IoT
SiteWise assets represent the cameras that stream video to each core device. Each camera's asset
must be associated to the asset for the core device that connects to the camera. Camera assets have
properties that you can configure to specify a Kinesis video stream, an authentication secret, and video
streaming parameters. For more information about how to create and configure camera assets, see
Create resources for the edge connector for Kinesis Video Streams in the AWS IoT TwinMaker User
Guide.
• An AWS Secrets Manager secret for each IP camera. This secret must define a key-value pair, where the
key is RTSPStreamUrl, and the value is the URL for the camera. If the camera requires authentication,
include the user name and password in this URL. You can use a script to create a secret when you
create the resources that this component requires. For more information, see Create resources for the
edge connector for Kinesis Video Streams in the AWS IoT TwinMaker User Guide.
You can also use the Secrets Manager console and API to create additional secrets. For more
information, see Create a secret in the AWS Secrets Manager User Guide.
• The Greengrass token exchange role (p. 790) must allow the following AWS Secrets Manager, AWS
IoT SiteWise, and Kinesis Video Streams actions, as shown in the following example IAM policy.
Note
This example policy allows the device to get the value of secrets named IPCamera1Url and
IPCamera2Url. When you configure each IP camera, you specify a secret that contains the
URL for that camera. If the camera requires authentication, you also specify a user name and
password in the URL. The core device's token exchange role must allow access to the secret for
each IP camera to connect.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"secretsmanager:GetSecretValue"
],
"Effect": "Allow",
"Resource": [
"arn:aws:secretsmanager:region:account-id:secret:IPCamera1Url",
"arn:aws:secretsmanager:region:account-id:secret:IPCamera2Url"
]
},
{
"Action": [
"iotsitewise:BatchPutAssetPropertyValue",
"iotsitewise:DescribeAsset",
"iotsitewise:DescribeAssetModel",
"iotsitewise:DescribeAssetProperty",
"iotsitewise:GetAssetPropertyValue",
"iotsitewise:ListAssetRelationships",
"iotsitewise:ListAssets",
"iotsitewise:ListAssociatedAssets",
"kinesisvideo:CreateStream",
"kinesisvideo:DescribeStream",
"kinesisvideo:GetDataEndpoint",
"kinesisvideo:PutMedia",
"kinesisvideo:TagStream"
],
"Effect": "Allow",
"Resource": [
"*"
]
222
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
}
]
}
Note
If you use a customer managed AWS Key Management Service key to encrypt secrets, the
device role must also allow the kms:Decrypt action.
Endpoints and ports
This component must be able to perform outbound requests to the following endpoints and ports, in
addition to endpoints and ports required for basic operation. For more information, see Allow device
traffic through a proxy or firewall (p. 807).
Endpoint Port Required Description
kinesisvideo.region.amazonaws.com 443 Yes Upload data
to Kinesis
Video
Streams.
443
data.iotsitewise.region.amazonaws.com Yes Publish
video stream
metadata
to AWS IoT
SiteWise.
443
secretsmanager.region.amazonaws.com Yes Download
camera URL
secrets to
the core
device.
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 224) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
The following table lists the dependencies for version 1.0.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.6.0 Hard
Token exchange ^2.0.0 Hard
service (p. 407)
Stream manager (p. 398) ^2.0.0 Hard
For more information about component dependencies, see the component recipe reference (p. 473).
223
AWS IoT Greengrass Developer Guide, Version 2
Configuration
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
SiteWiseAssetIdForHub
The ID of the AWS IoT SiteWise asset that represents this core device. For more information about
how to create this asset and use it to interact with this component, see AWS IoT TwinMaker video
stream integration in the AWS IoT TwinMaker User Guide.
Example Example: Configuration merge update
{
"SiteWiseAssetIdForHub": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
}
Licenses
This component includes the following third-party software/licensing:
• Quartz Job Scheduler / Apache License 2.0
• Java bindings for GStreamer 1.x / GNU Lesser General Public License v3.0
Usage
To configure and interact with this component, you can set properties on the AWS IoT SiteWise assets
that represent the core device and the IP cameras where it connects. You can also visualize and interact
with video streams in Grafana dashboards through AWS IoT TwinMaker. For more information, see AWS
IoT TwinMaker video stream integration in the AWS IoT TwinMaker User Guide.
Local log file
This component uses the following log file.
/greengrass/v2/logs/aws.iot.EdgeConnectorForKVS.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 with the path to the AWS IoT Greengrass root folder.
sudo tail -f /greengrass/v2/logs/greengrass.log
Changelog
The following table describes the changes in each version of the component.
Version Changes
1.0.0 Initial version.
224
AWS IoT Greengrass Developer Guide, Version 2
See also
See also
• What is AWS IoT TwinMaker? in the AWS IoT TwinMaker User Guide
• AWS IoT TwinMaker video stream integration in the AWS IoT TwinMaker User Guide
• Create resources for the edge connector for Kinesis Video Streams in the AWS IoT TwinMaker User
Guide
• Install the edge connector for Kinesis Video Streams component in the AWS IoT TwinMaker User Guide
• Configure AWS IoT SiteWise resources for the edge connector for Kinesis Video Streams in the AWS IoT
TwinMaker User Guide
• What is AWS IoT SiteWise? in the AWS IoT SiteWise User Guide
• Updating attribute values in the AWS IoT SiteWise User Guide
• What is AWS Secrets Manager? in the AWS Secrets Manager User Guide
• Create and manage secrets in the AWS Secrets Manager User Guide
Greengrass CLI
The Greengrass CLI component (aws.greengrass.Cli) provides a local command-line interface that
you can use on core devices to develop and debug components locally. The Greengrass CLI lets you
create local deployments and restart components on the core device, for example.
You can install this component when you install the AWS IoT Greengrass Core software. For more
information, see Getting started with AWS IoT Greengrass V2 (p. 31).
Important
We recommend that you use this component in only development environments, not production
environments. This component provides access to information and operations that you typically
won't need in a production environment. Follow the principle of least privilege by deploying this
component to only core devices where you need it.
After you install this component, run the following command to view its help documentation. When
this component installs, it adds a symbolic link to greengrass-cli in the /greengrass/v2/bin
folder. You can run the Greengrass CLI from this path or add it to your PATH environment variable to run
greengrass-cli without its absolute path.
Linux or Unix
/greengrass/v2/bin/greengrass-cli help
Windows
C:\greengrass\v2\bin\greengrass-cli help
The following command restarts a component named com.example.HelloWorld, for example.
Linux or Unix
sudo /greengrass/v2/bin/greengrass-cli component restart --names
"com.example.HelloWorld"
Windows
C:\greengrass\v2\bin\greengrass-cli component restart --names "com.example.HelloWorld"
225
AWS IoT Greengrass Developer Guide, Version 2
Versions
For more information, see Greengrass Command Line Interface (p. 428).
Topics
• Versions (p. 226)
• Type (p. 226)
• Operating system (p. 226)
• Requirements (p. 226)
• Dependencies (p. 227)
• Configuration (p. 228)
• Local log file (p. 229)
• Changelog (p. 229)
Versions
This component has the following versions:
• 2.5.x
• 2.4.x
• 2.3.x
• 2.2.x
• 2.1.x
• 2.0.x
Type
This component is a plugin component (aws.greengrass.plugin). The Greengrass nucleus (p. 181)
runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when
you change this component's version on the core device.
This component uses the same log file as the Greengrass nucleus. For more information, see Monitor
AWS IoT Greengrass logs (p. 506).
For more information, see Component types (p. 441).
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
Requirements
This component has the following requirements:
• You must be authorized to use the Greengrass CLI to interact with the AWS IoT Greengrass Core
software. Do one of the following to use the Greengrass CLI:
• Use the system user that runs the AWS IoT Greengrass Core software.
226
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
• Use a user with root or adminstrative permissions. On Linux core devices, you can use sudo to gain
root permissions.
• Use a system user that's in a group that you specify in the AuthorizedPosixGroups or
AuthorizedWindowsGroups configuration parameters when you deploy the component. For more
information, see Greengrass CLI component configuration (p. 228).
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 229) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.5.0 - 2.5.2
The following table lists the dependencies for versions 2.5.0 through 2.5.2 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.5.0 <2.6.0 Soft
2.4.0
The following table lists the dependencies for version 2.4.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.1.0 <2.5.0 Soft
2.3.0
The following table lists the dependencies for version 2.3.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.1.0 <2.4.0 Soft
2.2.0
The following table lists the dependencies for version 2.2.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.1.0 <2.3.0 Soft
2.1.0
The following table lists the dependencies for version 2.1.0 of this component.
227
AWS IoT Greengrass Developer Guide, Version 2
Configuration
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.1.0 <2.2.0 Soft
2.0.x
The following table lists the dependencies for version 2.0.x of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.1.0 Soft
Note
The minimum compatible version of the Greengrass nucleus corresponds to the patch
version of the Greengrass CLI component.
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
2.5.x
AuthorizedPosixGroups
(Optional) A string that contains a comma-separated list of system groups. You authorize these
system groups to use the Greengrass CLI to interact with the AWS IoT Greengrass Core software.
You can specify group names or group IDs. For example, group1,1002,group3 authorizes
three system groups (group1, 1002, and group3) to use the Greengrass CLI.
If you don't specify any groups to authorize, you can use the Greengrass CLI as the root user
(sudo) or as the system user that runs the AWS IoT Greengrass Core software.
AuthorizedWindowsGroups
(Optional) A string that contains a comma-separated list of system groups. You authorize these
system groups to use the Greengrass CLI to interact with the AWS IoT Greengrass Core software.
You can specify group names or group IDs. For example, group1,1002,group3 authorizes
three system groups (group1, 1002, and group3) to use the Greengrass CLI.
If you don't specify any groups to authorize, you can use the Greengrass CLI as an administrator
or as the system user that runs the AWS IoT Greengrass Core software.
Example Example: Configuration merge update
The following example configuration specifies to authorize three POSIX system groups (group1,
1002, and group3) and two Windows user groups (Device Operators and QA Engineers) to use
the Greengrass CLI.
{
"AuthorizedPosixGroups": "group1,1002,group3",
"AuthorizedWindowsGroups": "Device Operators,QA Engineers"
228
AWS IoT Greengrass Developer Guide, Version 2
Local log file
2.4.x - 2.0.x
AuthorizedPosixGroups
(Optional) A string that contains a comma-separated list of system groups. You authorize these
system groups to use the Greengrass CLI to interact with the AWS IoT Greengrass Core software.
You can specify group names or group IDs. For example, group1,1002,group3 authorizes
three system groups (group1, 1002, and group3) to use the Greengrass CLI.
If you don't specify any groups to authorize, you can use the Greengrass CLI as the root user
(sudo) or as the system user that runs the AWS IoT Greengrass Core software.
Example Example: Configuration merge update
The following example configuration specifies to authorize three system groups (group1, 1002, and
group3) to use the Greengrass CLI.
{
"AuthorizedPosixGroups": "group1,1002,group3"
}
Local log file
This component uses the same log file as the Greengrass nucleus (p. 181) component.
Linux
/greengrass/v2/logs/greengrass.log
Windows
C:\greengrass\v2\logs\greengrass.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
Linux
sudo tail -f /greengrass/v2/logs/greengrass.log
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
Changelog
The following table describes the changes in each version of the component.
229
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Device Defender
Version Changes
2.5.2 Version updated for Greengrass nucleus version 2.5.2 release.
2.5.1 Version updated for Greengrass nucleus version 2.5.1 release.
2.5.0 New features
• Adds support for core devices that run Windows.
• Adds the new AuthorizedWindowsGroups configuration parameter that
you can specify to authorize system groups to use the Greengrass CLI on
Windows devices.
• Adds the windowsUser parameter for local deployments. You can use this
parameter specify the user to use to run components on a Windows core
device.
2.4.0 New features
• Adds support for system resource limits. When you create a local
deployment, you can configure the maximum amount of CPU and
RAM usage that each component's processes can use on the core
device. For more information, see Configure system resource limits for
components (p. 164) and the deployment create command (p. 434).
2.3.0 Version updated for Greengrass nucleus version 2.3.0 release.
2.2.0 Version updated for Greengrass nucleus version 2.2.0 release.
2.1.0 Version updated for Greengrass nucleus version 2.1.0 release.
2.0.5 Version updated for Greengrass nucleus version 2.0.5 release.
2.0.4 Version updated for Greengrass nucleus version 2.0.4 release.
2.0.3 Initial version.
AWS IoT Device Defender
The AWS IoT Device Defender component (aws.greengrass.DeviceDefender) notifies
administrators about changes in the state of Greengrass core devices. This can help identify unusual
behavior that might indicate a compromised device. For more information, see AWS IoT Device Defender
in the AWS IoT Core Developer Guide.
This component reads system metrics on the core device. Then, it publishes the metrics to AWS IoT
Device Defender. For more information about how to read and interpret the metrics that this component
reports, see Device metrics document specification in the AWS IoT Core Developer Guide.
Note
This component provides similar functionality to the Device Defender connector in AWS IoT
Greengrass V1. For more information, see Device Defender connector in the AWS IoT Greengrass
V1 Developer Guide.
Topics
• Versions (p. 231)
• Type (p. 231)
• Operating system (p. 231)
230
AWS IoT Greengrass Developer Guide, Version 2
Versions
• Requirements (p. 231)
• Dependencies (p. 233)
• Configuration (p. 235)
• Input data (p. 237)
• Output data (p. 237)
• Local log file (p. 238)
• Licenses (p. 239)
• Changelog (p. 239)
Versions
This component has the following versions:
• 3.0.x
• 2.0.x
For information about changes in each version of the component, see the changelog (p. 239).
Type
3.0.x
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
2.0.x
This component is a Lambda component (aws.greengrass.lambda). The Greengrass
nucleus (p. 181) runs this component's Lambda function using the Lambda launcher
component (p. 252).
For more information, see Component types (p. 441).
Operating system
3.0.x
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
2.0.x
This component can be installed on Linux core devices only.
Requirements
This component has the following requirements:
231
AWS IoT Greengrass Developer Guide, Version 2
Requirements
3.0.x
• Python version 3.7 installed on the core device and added to the PATH environment variable.
• AWS IoT Device Defender configured to use the Detect feature to monitor violations. For more
information, see Detect in the AWS IoT Core Developer Guide.
2.0.x
• Your core device must meet the requirements to run Lambda functions. If you want the core
device to run containerized Lambda functions, the device must meet the requirements to do so.
For more information, see Lambda function requirements (p. 64).
• Python version 3.7 installed on the core device and added to the PATH environment variable.
• AWS IoT Device Defender configured to use the Detect feature to monitor violations. For more
information, see Detect in the AWS IoT Core Developer Guide.
• The psutil library installed on the core device. Version 5.7.0 is the latest version that is verified to
work with the component.
• The cbor library installed on the core device. Version 1.0.0 is the latest version that is verified to
work with the component.
• To receive output data from this component, you must merge the following configuration update
for the legacy subscription router component (p. 260) when you deploy this component. The
legacy subscription router component (aws.greengrass.LegacySubscriptionRouter) is
a dependency of this component. This configuration specifies the topic where this component
publishes responses.
Legacy subscription router v2.1.x
{
"subscriptions": {
"aws-greengrass-device-defender": {
"id": "aws-greengrass-device-defender",
"source": "component:aws.greengrass.DeviceDefender",
"subject": "$aws/things/+/defender/metrics/json",
"target": "cloud"
}
}
}
Legacy subscription router v2.0.x
{
"subscriptions": {
"aws-greengrass-device-defender": {
"id": "aws-greengrass-device-defender",
"source": "arn:aws:lambda:region:aws:function:aws-greengrass-device-
defender:version",
"subject": "$aws/things/+/defender/metrics/json",
"target": "cloud"
}
}
}
• Replace region with the AWS Region that you use.
• Replace version with the version of the Lambda function that this component runs.
To find the Lambda function version, you must view the recipe for the version of this
component that you want to deploy. Open this component's details page in the AWS IoT
Greengrass console, and look for the Lambda function key-value pair. This key-value pair
contains the name and version of the Lambda function.
232
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
Important
You must update the Lambda function version on the legacy subscription router
every time you deploy this component. This ensures that you use the correct Lambda
function version for the component version that you deploy.
For more information, see Create deployments (p. 493).
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 239) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
3.0.0 and 3.0.1
The following table lists the dependencies for versions 3.0.0 and 3.0.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <3.0.0 Soft
Token exchange >=0.0.0 Hard
service (p. 407)
2.0.8
The following table lists the dependencies for version 2.0.8 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.6.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.7
The following table lists the dependencies for version 2.0.7 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
233
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
Dependency Compatible versions Dependency type
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.6
The following table lists the dependencies for version 2.0.6 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.5
The following table lists the dependencies for version 2.0.5 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.4
The following table lists the dependencies for version 2.0.4 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.2.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.3
The following table lists the dependencies for version 2.0.3 of this component.
234
AWS IoT Greengrass Developer Guide, Version 2
Configuration
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.3 <2.1.0 Hard
Lambda launcher (p. 252) >=1.0.0 Hard
Lambda runtimes (p. 258) >=1.0.0 Soft
Token exchange >=1.0.0 Hard
service (p. 407)
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
3.0.x
SampleIntervalSeconds
(Optional) The amount of time in seconds between each cycle where the component gathers
and reports metrics.
The minimum value is 300 seconds (5 minutes).
Default: 300 seconds
UseInstaller
(Optional) Boolean value that defines whether to use the installer script in this component to
install this component's dependencies.
Set this value to false if you want to use a custom script to install dependencies, or if you want
to include runtime dependencies in a pre-built Linux image. To use this component, you will
need to install the following libraries, including any dependencies, and make them available to
the default Greengrass system user.
• AWS IoT Device SDK v2 for Python
• cbor library. Version 1.0.0 is the latest version that is verified to work with the component.
• psutil library. Version 5.7.0 is the latest version that is verified to work with the component.
Default: true
2.0.x
Note
This component's default configuration includes Lambda function parameters. We
recommend that you edit only the following parameters to configure this component on
your devices.
lambdaParams
An object that contains the parameters for this component's Lambda function. This object
contains the following information:
EnvironmentVariables
An object that contains the Lambda function's parameters. This object contains the
following information:
235
AWS IoT Greengrass Developer Guide, Version 2
Configuration
PROCFS_PATH
(Optional) The path to the /proc folder.
• To run this component in a container, use the default value, /host-proc. The
component runs in a container by default.
• To run this component in no container mode, specify /proc for this parameter.
Default: /host-proc. This is the default path where this component mounts the /
proc folder in the container.
Note
This component has read-only access to this folder.
SAMPLE_INTERVAL_SECONDS
(Optional) The amount of time in seconds between each cycle where the component
gathers and reports metrics.
The minimum value is 300 seconds (5 minutes).
Default: 300 seconds
containerMode
(Optional) The containerization mode for this component. Choose from the following options:
• GreengrassContainer – The component runs in an isolated runtime environment inside the
AWS IoT Greengrass container.
• NoContainer – The component doesn't run in an isolated runtime environment.
If you specify this option, you must specify /proc for the PROCFS_PATH environment variable
parameter.
Default: GreengrassContainer
containerParams
(Optional) An object that contains the container parameters for this component. The component
uses these parameters if you specify GreengrassContainer for containerMode.
This object contains the following information:
memorySize
(Optional) The amount of memory (in kilobytes) to allocate to the component.
Defaults to 50,000 KB.
pubsubTopics
(Optional) An object that contains the topics where the component subscribes to receive
messages. You can specify each topic and whether the component subscribes to MQTT topics
from AWS IoT Core or local publish/subscribe topics.
This object contains the following information:
0 – This is an array index as a string.
An object that contains the following information:
type
(Optional) The type of publish/subscribe messaging that this component uses to
subscribe to messages. Choose from the following options:
• Pubsub – Subscribe to local publish/subscribe messages. If you choose this option,
the topic can't contain MQTT wildcards. For more information about how to send
messages from custom component when you specify this option, see Publish/
subscribe local messages (p. 561).
236
AWS IoT Greengrass Developer Guide, Version 2
Input data
• IotCore – Subscribe to AWS IoT Core MQTT messages. If you choose this option,
the topic can contain MQTT wildcards. For more information about how to send
messages from custom components when you specify this option, see Publish/
subscribe AWS IoT Core MQTT messages (p. 586).
Default: Pubsub
topic
(Optional) The topic to which the component subscribes to receive messages. If you
specify IotCore for type, you can use MQTT wildcards (+ and #) in this topic.
Example Example: Configuration merge update (container mode)
{
"lambdaExecutionParameters": {
"EnvironmentVariables": {
"PROCFS_PATH": "/host_proc"
}
},
"containerMode": "GreengrassContainer"
}
Example Example: Configuration merge update (no container mode)
{
"lambdaExecutionParameters": {
"EnvironmentVariables": {
"PROCFS_PATH": "/proc"
}
},
"containerMode": "NoContainer"
}
Input data
This component doesn't accept messages as input data.
Output data
This component publishes security metrics to the following reserved topic for AWS IoT Device Defender.
This component replaces coreDeviceName with the name of the core device when it publishes the
metrics.
Topic (AWS IoT Core MQTT): $aws/things/coreDeviceName/defender/metrics/json
Example Example output
{
"header": {
"report_id": 1529963534,
"version": "1.0"
},
"metrics": {
"listening_tcp_ports": {
"ports": [
{
"interface": "eth0",
237
AWS IoT Greengrass Developer Guide, Version 2
Local log file
"port": 24800
},
{
"interface": "eth0",
"port": 22
},
{
"interface": "eth0",
"port": 53
}
],
"total": 3
},
"listening_udp_ports": {
"ports": [
{
"interface": "eth0",
"port": 5353
},
{
"interface": "eth0",
"port": 67
}
],
"total": 2
},
"network_stats": {
"bytes_in": 1157864729406,
"bytes_out": 1170821865,
"packets_in": 693092175031,
"packets_out": 738917180
},
"tcp_connections": {
"established_connections":{
"connections": [
{
"local_interface": "eth0",
"local_port": 80,
"remote_addr": "192.168.0.1:8000"
},
{
"local_interface": "eth0",
"local_port": 80,
"remote_addr": "192.168.0.1:8000"
}
],
"total": 2
}
}
}
}
For more information about the metrics that this component reports, see Device metrics document
specification in the AWS IoT Core Developer Guide.
Local log file
This component uses the following log file.
Linux
/greengrass/v2/logs/aws.greengrass.DeviceDefender.log
238
AWS IoT Greengrass Developer Guide, Version 2
Licenses
Windows
C:\greengrass\v2\logs\aws.greengrass.DeviceDefender.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
Linux
sudo tail -f /greengrass/v2/logs/aws.greengrass.DeviceDefender.log
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\aws.greengrass.DeviceDefender.log -Tail 10 -Wait
Licenses
This component is released under the Greengrass Core Software License Agreement.
Changelog
The following table describes the changes in each version of the component.
3.0.x
Version Changes
3.0.1 Fixes an issue with how the component calculates delta values for metrics.
3.0.0 Initial version.
This version is no longer available.
2.0.x
Version Changes
2.0.8 Version updated for Greengrass nucleus version 2.5.0 release.
2.0.7 Version updated for Greengrass nucleus version 2.4.0 release.
2.0.6 Version updated for Greengrass nucleus version 2.3.0 release.
2.0.5 Version updated for Greengrass nucleus version 2.2.0 release.
2.0.4 Version updated for Greengrass nucleus version 2.1.0 release.
2.0.3 Initial version.
239
AWS IoT Greengrass Developer Guide, Version 2
IP detector
IP detector
The IP detector component (aws.greengrass.clientdevices.IPDetector) does the following:
• Monitors the Greengrass core device's network connectivity information. This information includes the
core device's network endpoints and the port where an MQTT broker operates.
• Updates the core device's connectivity information in the AWS IoT Greengrass cloud service.
Client devices can use Greengrass cloud discovery to retrieve associated core devices' connectivity
information. Then, client devices can try to connect to each core device until they successfully connect.
Note
Client devices are local IoT devices that connect to a Greengrass core device to send
MQTT messages and data to process. For more information, see Interact with local IoT
devices (p. 638).
The IP detector component replaces a core device's existing connectivity information with the
information it detects. Because this component removes existing information, you can either use the IP
detector component, or manually manage connectivity information.
Note
The IP detector component detects only IPv4 addresses.
Topics
• Versions (p. 240)
• Type (p. 240)
• Operating system (p. 241)
• Requirements (p. 241)
• Dependencies (p. 241)
• Configuration (p. 242)
• Local log file (p. 243)
• Changelog (p. 243)
Versions
This component has the following versions:
• 2.1.x
• 2.0.x
Type
This component is a plugin component (aws.greengrass.plugin). The Greengrass nucleus (p. 181)
runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when
you change this component's version on the core device.
This component uses the same log file as the Greengrass nucleus. For more information, see Monitor
AWS IoT Greengrass logs (p. 506).
For more information, see Component types (p. 441).
240
AWS IoT Greengrass Developer Guide, Version 2
Operating system
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
Requirements
This component has the following requirements:
• The Greengrass service role (p. 796) must be associated to your AWS account and allow the
iot:GetThingShadow and iot:UpdateThingShadow permissions.
• The core device's AWS IoT policy must allow the greengrass:UpdateConnectivityInfo
permission. For more information, see AWS IoT policies for data plane operations (p. 774) and
Minimal AWS IoT policy to support client devices (p. 779).
• If you configure the core device's MQTT broker component to use a port other than the default
port 8883, you must use IP detector v2.1.0 or later. Configure it to report the port where the broker
operates.
• If you have a complex network setup, the IP detector component might not be able to identify the
endpoints where client devices can connect to the core device. If the IP detector component can't
manage the endpoints, you must manually manage the core device endpoints instead. For example,
if the core device is behind a router that forwards the MQTT broker port to it, you must specify the
router's IP address as an endpoint for the core device. For more information, see Manage core device
endpoints (p. 654).
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 243) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.1.1
The following table lists the dependencies for version 2.1.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.2.0 <2.6.0 Soft
2.1.0 and 2.0.2
The following table lists the dependencies for versions 2.1.0 and 2.0.2 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.2.0 <2.5.0 Soft
241
AWS IoT Greengrass Developer Guide, Version 2
Configuration
2.0.1
The following table lists the dependencies for version 2.0.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.2.0 <2.4.0 Soft
2.0.0
The following table lists the dependencies for version 2.0.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.2.0 <2.3.0 Soft
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
2.1.x
defaultPort
(Optional) The MQTT broker port to report when this component detects IP addresses. You must
specify this parameter if you configure the MQTT broker to use a different port than the default
port 8883.
Default: 8883
includeIPv4LoopbackAddrs
(Optional) You can enable this option to detect and report IPv4 loopback addresses. These are
IP addresses, such as localhost, where a device can communicate with itself. Use this option in
test environments where the core device and client device run on the same system.
Default: false
includeIPv4LinkLocalAddrs
(Optional) You can enable this option to detect and report IPv4 link-local addresses. Use this
option if the core device's network doesn't have Dynamic Host Configuration Protocol (DHCP) or
statically assigned IP addresses.
Default: false
2.0.x
includeIPv4LoopbackAddrs
(Optional) You can enable this option to detect and report IPv4 loopback addresses. These are
IP addresses, such as localhost, where a device can communicate with itself. Use this option in
test environments where the core device and client device run on the same system.
Default: false
242
AWS IoT Greengrass Developer Guide, Version 2
Local log file
includeIPv4LinkLocalAddrs
(Optional) You can enable this option to detect and report IPv4 link-local addresses. Use this
option if the core device's network doesn't have Dynamic Host Configuration Protocol (DHCP) or
statically assigned IP addresses.
Default: false
Local log file
This component uses the same log file as the Greengrass nucleus (p. 181) component.
Linux
/greengrass/v2/logs/greengrass.log
Windows
C:\greengrass\v2\logs\greengrass.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
Linux
sudo tail -f /greengrass/v2/logs/greengrass.log
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.1.1 Version updated for Greengrass nucleus version 2.5.0 release.
2.1.0 Improvements
• Adds the defaultPort parameter, which enables you to use a non-default
MQTT broker port.
• Updates to make log messages more clear.
2.0.2 Version updated for Greengrass nucleus version 2.4.0 release.
2.0.1 Version updated for Greengrass nucleus version 2.3.0 release.
2.0.0 Initial version.
243
AWS IoT Greengrass Developer Guide, Version 2
Kinesis Data Firehose
Kinesis Data Firehose
The Kinesis Data Firehose component (aws.greengrass.KinesisFirehose) publishes data through
Amazon Kinesis Data Firehose delivery streams to destinations, such as Amazon S3, Amazon Redshift,
and Amazon OpenSearch Service. For more information, see What is Amazon Kinesis Data Firehose? in
the Amazon Kinesis Data Firehose Developer Guide.
To publish to a Kinesis delivery stream with this component, publish a message to a topic where this
component subscribes. By default, this component subscribes to the kinesisfirehose/message and
kinesisfirehose/message/binary/# local publish/subscribe (p. 561) topics. You can specify other
topics, including AWS IoT Core MQTT topics, when you deploy this component.
Note
This component provides similar functionality to the Kinesis Data Firehose connector in AWS
IoT Greengrass V1. For more information, see Kinesis Data Firehose connector in the AWS IoT
Greengrass V1 Developer Guide.
Topics
• Versions (p. 244)
• Type (p. 244)
• Operating system (p. 244)
• Requirements (p. 244)
• Dependencies (p. 246)
• Configuration (p. 248)
• Input data (p. 250)
• Output data (p. 251)
• Local log file (p. 251)
• Licenses (p. 252)
• Changelog (p. 252)
• See also (p. 252)
Versions
This component has the following versions:
• 2.0.x
Type
This component is a Lambda component (aws.greengrass.lambda). The Greengrass nucleus (p. 181)
runs this component's Lambda function using the Lambda launcher component (p. 252).
For more information, see Component types (p. 441).
Operating system
This component can be installed on Linux core devices only.
Requirements
This component has the following requirements:
244
AWS IoT Greengrass Developer Guide, Version 2
Requirements
• Your core device must meet the requirements to run Lambda functions. If you want the core device
to run containerized Lambda functions, the device must meet the requirements to do so. For more
information, see Lambda function requirements (p. 64).
• Python version 3.7 installed on the core device and added to the PATH environment variable.
• The Greengrass device role (p. 790) must allow the firehose:PutRecord and
firehose:PutRecordBatch actions, as shown in the following example IAM policy.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"firehose:PutRecord",
"firehose:PutRecordBatch"
],
"Effect": "Allow",
"Resource": [
"arn:aws:firehose:region:account-id:deliverystream/stream-name"
]
}
]
}
You can dynamically override the default delivery stream in the input message payload for this
component. If your application uses this feature, the IAM policy must include all target streams as
resources. You can grant granular or conditional access to resources (for example, by using a wildcard *
naming scheme).
• To receive output data from this component, you must merge the following configuration update for
the legacy subscription router component (p. 260) when you deploy this component. The legacy
subscription router component (aws.greengrass.LegacySubscriptionRouter) is a dependency
of this component. This configuration specifies the topic where this component publishes responses.
Legacy subscription router v2.1.x
{
"subscriptions": {
"aws-greengrass-kinesisfirehose": {
"id": "aws-greengrass-kinesisfirehose",
"source": "component:aws.greengrass.KinesisFirehose",
"subject": "kinesisfirehose/message/status",
"target": "cloud"
}
}
}
Legacy subscription router v2.0.x
{
"subscriptions": {
"aws-greengrass-kinesisfirehose": {
"id": "aws-greengrass-kinesisfirehose",
"source": "arn:aws:lambda:region:aws:function:aws-greengrass-
kinesisfirehose:version",
"subject": "kinesisfirehose/message/status",
"target": "cloud"
}
}
}
• Replace region with the AWS Region that you use.
245
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
• Replace version with the version of the Lambda function that this component runs. To find
the Lambda function version, you must view the recipe for the version of this component that
you want to deploy. Open this component's details page in the AWS IoT Greengrass console, and
look for the Lambda function key-value pair. This key-value pair contains the name and version
of the Lambda function.
Important
You must update the Lambda function version on the legacy subscription router every
time you deploy this component. This ensures that you use the correct Lambda function
version for the component version that you deploy.
For more information, see Create deployments (p. 493).
Endpoints and ports
This component must be able to perform outbound requests to the following endpoints and ports, in
addition to endpoints and ports required for basic operation. For more information, see Allow device
traffic through a proxy or firewall (p. 807).
Endpoint Port Required Description
firehose.region.amazonaws.com 443 Yes Upload
data to
Kinesis Data
Firehose.
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 252) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.0.8
The following table lists the dependencies for version 2.0.8 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.6.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.7
The following table lists the dependencies for version 2.0.7 of this component.
246
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.6
The following table lists the dependencies for version 2.0.6 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.5
The following table lists the dependencies for version 2.0.5 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.4
The following table lists the dependencies for version 2.0.4 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.2.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
247
AWS IoT Greengrass Developer Guide, Version 2
Configuration
2.0.3
The following table lists the dependencies for version 2.0.3 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.3 <2.1.0 Hard
Lambda launcher (p. 252) >=1.0.0 Hard
Lambda runtimes (p. 258) >=1.0.0 Soft
Token exchange >=1.0.0 Hard
service (p. 407)
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
Note
This component's default configuration includes Lambda function parameters. We recommend
that you edit only the following parameters to configure this component on your devices.
lambdaParams
An object that contains the parameters for this component's Lambda function. This object contains
the following information:
EnvironmentVariables
An object that contains the Lambda function's parameters. This object contains the following
information:
DEFAULT_DELIVERY_STREAM_ARN
The ARN of the default Kinesis Data Firehose delivery stream where the component sends
data. You can override the destination stream with the delivery_stream_arn property in
the input message payload.
Note
The core device role must allow the required actions on all target delivery streams.
For more information, see Requirements (p. 244).
PUBLISH_INTERVAL
(Optional) The maximum number of seconds to wait before the component publishes
batched data to Kinesis Data Firehose. To configure the component to publish metrics as it
receives them, which means without batching, specify 0.
This value can be at most 900 seconds.
Default: 10 seconds
DELIVERY_STREAM_QUEUE_SIZE
(Optional) The maximum number of records to retain in memory before the component
rejects new records for the same delivery stream.
This value must be at least 2,000 records.
248
AWS IoT Greengrass Developer Guide, Version 2
Configuration
Default: 5,000 records
containerMode
(Optional) The containerization mode for this component. Choose from the following options:
• NoContainer – The component doesn't run in an isolated runtime environment.
• GreengrassContainer – The component runs in an isolated runtime environment inside the
AWS IoT Greengrass container.
Default: GreengrassContainer
containerParams
(Optional) An object that contains the container parameters for this component. The component
uses these parameters if you specify GreengrassContainer for containerMode.
This object contains the following information:
memorySize
(Optional) The amount of memory (in kilobytes) to allocate to the component.
Defaults to 64 MB (65,535 KB).
pubsubTopics
(Optional) An object that contains the topics where the component subscribes to receive messages.
You can specify each topic and whether the component subscribes to MQTT topics from AWS IoT
Core or local publish/subscribe topics.
This object contains the following information:
0 – This is an array index as a string.
An object that contains the following information:
type
(Optional) The type of publish/subscribe messaging that this component uses to subscribe
to messages. Choose from the following options:
• Pubsub – Subscribe to local publish/subscribe messages. If you choose this option, the
topic can't contain MQTT wildcards. For more information about how to send messages
from custom component when you specify this option, see Publish/subscribe local
messages (p. 561).
• IotCore – Subscribe to AWS IoT Core MQTT messages. If you choose this option, the
topic can contain MQTT wildcards. For more information about how to send messages
from custom components when you specify this option, see Publish/subscribe AWS IoT
Core MQTT messages (p. 586).
Default: Pubsub
topic
(Optional) The topic to which the component subscribes to receive messages. If you specify
IotCore for type, you can use MQTT wildcards (+ and #) in this topic.
Example Example: Configuration merge update (container mode)
{
"lambdaExecutionParameters": {
"EnvironmentVariables": {
"DEFAULT_DELIVERY_STREAM_ARN": "arn:aws:firehose:us-
west-2:123456789012:deliverystream/mystream"
}
},
249
AWS IoT Greengrass Developer Guide, Version 2
Input data
"containerMode": "GreengrassContainer"
}
Example Example: Configuration merge update (no container mode)
{
"lambdaExecutionParameters": {
"EnvironmentVariables": {
"DEFAULT_DELIVERY_STREAM_ARN": "arn:aws:firehose:us-
west-2:123456789012:deliverystream/mystream"
}
},
"containerMode": "NoContainer"
}
Input data
This component accepts stream content on the following topics and sends the content to the target
delivery stream. The component accepts two types of input data:
• JSON data on the kinesisfirehose/message topic.
• Binary data on the kinesisfirehose/message/binary/# topic.
Default topic for JSON data (local publish/subscribe): kinesisfirehose/message
The message accepts the following properties. Input messages must be in JSON format.
request
The data to send to the delivery stream and the target delivery stream, if different from the
default stream.
Type: object that contains the following information:
data
The data to send to the delivery stream.
Type: string
delivery_stream_arn
(Optional) The ARN of the target Kinesis Data Firehose delivery stream. Specify this
property to override the default delivery stream.
Type: string
id
An arbitrary ID for the request. Use this property to map an input request to an output
response. When you specify this property, the component sets the id property in the response
object to this value.
Type: string
Example Example input
{
"request": {
"delivery_stream_arn": "arn:aws:firehose:region:account-id:deliverystream/stream2-
name",
"data": "Data to send to the delivery stream."
250
AWS IoT Greengrass Developer Guide, Version 2
Output data
},
"id": "request123"
}
Default topic for binary data (local publish/subscribe): kinesisfirehose/message/binary/#
Use this topic to send a message that contains binary data. The component doesn't parse binary
data. The component streams the data as is.
To map the input request to an output response, replace the # wildcard in the message topic with
an arbitrary request ID. For example, if you publish a message to kinesisfirehose/message/
binary/request123, the id property in the response object is set to request123.
If you don't want to map a request to a response, you can publish your messages to
kinesisfirehose/message/binary/. Be sure to include the trailing slash (/).
Output data
This component publishes responses as output data on the following MQTT topic by default. You
must specify this topic as the subject in the configuration for the legacy subscription router
component (p. 260). For more information about how to subscribe to messages on this topic in your
custom components, see Publish/subscribe AWS IoT Core MQTT messages (p. 586).
Default topic (AWS IoT Core MQTT): kinesisfirehose/message/status
Example Example output
The response contains the status of each data record sent in the batch.
{
"response": [
{
"ErrorCode": "error",
"ErrorMessage": "test error",
"id": "request123",
"status": "fail"
},
{
"firehose_record_id": "xyz2",
"id": "request456",
"status": "success"
},
{
"firehose_record_id": "xyz3",
"id": "request890",
"status": "success"
}
]
}
Note
If the component detects an error that can be retried, such as a connection error, it retries the
publish in the next batch.
Local log file
This component uses the following log file.
/greengrass/v2/logs/aws.greengrass.KinesisFirehose.log
251
AWS IoT Greengrass Developer Guide, Version 2
Licenses
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 with the path to the AWS IoT Greengrass root folder.
sudo tail -f /greengrass/v2/logs/greengrass.log
Licenses
This component includes the following third-party software/licensing:
• AWS SDK for Python (Boto3)/Apache License 2.0
• botocore/Apache License 2.0
• dateutil/PSF License
• docutils/BSD License, GNU General Public License (GPL), Python Software Foundation License, Public
Domain
• jmespath/MIT License
• s3transfer/Apache License 2.0
• urllib3/MIT License
This component is released under the Greengrass Core Software License Agreement.
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.0.8 Version updated for Greengrass nucleus version 2.5.0 release.
2.0.7 Version updated for Greengrass nucleus version 2.4.0 release.
2.0.6 Version updated for Greengrass nucleus version 2.3.0 release.
2.0.5 Version updated for Greengrass nucleus version 2.2.0 release.
2.0.4 Version updated for Greengrass nucleus version 2.1.0 release.
2.0.3 Initial version.
See also
• What is Amazon Kinesis Data Firehose? in the Amazon Kinesis Data Firehose Developer Guide
Lambda launcher
The Lambda launcher component (aws.greengrass.LambdaLauncher) starts and stops AWS Lambda
functions on AWS IoT Greengrass core devices. This component also sets up any containerization and
runs processes as the users that you specify.
252
AWS IoT Greengrass Developer Guide, Version 2
Versions
Note
When you deploy a Lambda function component to a core device, the deployment also includes
this component. For more information, see Run AWS Lambda functions (p. 523).
Topics
• Versions (p. 253)
• Type (p. 253)
• Operating system (p. 253)
• Requirements (p. 253)
• Dependencies (p. 253)
• Configuration (p. 254)
• Local log file (p. 254)
• Changelog (p. 254)
Versions
This component has the following versions:
• 2.0.x
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
Operating system
This component can be installed on Linux core devices only.
Requirements
This component has the following requirements:
• Your core device must meet the requirements to run Lambda functions. If you want the core device
to run containerized Lambda functions, the device must meet the requirements to do so. For more
information, see Lambda function requirements (p. 64).
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 254) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.0.9
The following table lists the dependencies for version 2.0.9 of this component.
253
AWS IoT Greengrass Developer Guide, Version 2
Configuration
Dependency Compatible versions Dependency type
Lambda manager (p. 255) >=2.0.0 <2.3.0 Hard
2.0.4 - 2.0.8
The following table lists the dependencies for versions 2.0.4 to 2.0.8 of this component.
Dependency Compatible versions Dependency type
Lambda manager (p. 255) >=2.0.0 <2.2.0 Hard
2.0.3
The following table lists the dependencies for version 2.0.3 of this component.
Dependency Compatible versions Dependency type
Lambda manager (p. 255) >=2.0.3 <2.1.0 Hard
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component doesn't have any configuration parameters.
Local log file
This component uses the following log file.
/greengrass/v2/logs/lambdaFunctionComponentName.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 with the path to the AWS IoT Greengrass root folder, and replace
lambdaFunctionComponentName with the name of the Lambda function component that this
component launches.
sudo tail -f /greengrass/v2/logs/lambdaFunctionComponentName.log
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.0.9 Version updated for Greengrass nucleus version 2.5.0 release.
2.0.8 Version updated for Greengrass nucleus version 2.4.0 release.
254
AWS IoT Greengrass Developer Guide, Version 2
Lambda manager
Version Changes
2.0.7 Version updated for Greengrass nucleus version 2.3.0 release.
2.0.6 General performance improvements and bug fixes.
2.0.4 Bug fixes and improvements
• Fixes an issue where the component doesn't correctly pass
AddGroupOwner to the Lambda function container.
2.0.3 Initial version.
Lambda manager
The Lambda manager component (aws.greengrass.LambdaManager) manages work items and
interprocess communication for AWS Lambda functions that run on the Greengrass core device.
Note
When you deploy a Lambda function component to a core device, the deployment also includes
this component. For more information, see Run AWS Lambda functions (p. 523).
Topics
• Versions (p. 255)
• Operating system (p. 255)
• Type (p. 255)
• Requirements (p. 256)
• Dependencies (p. 256)
• Configuration (p. 257)
• Local log file (p. 257)
• Changelog (p. 258)
Versions
This component has the following versions:
• 2.2.x
• 2.1.x
• 2.0.x
Operating system
This component can be installed on Linux core devices only.
Type
This component is a plugin component (aws.greengrass.plugin). The Greengrass nucleus (p. 181)
runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when
you change this component's version on the core device.
This component uses the same log file as the Greengrass nucleus. For more information, see Monitor
AWS IoT Greengrass logs (p. 506).
255
AWS IoT Greengrass Developer Guide, Version 2
Requirements
For more information, see Component types (p. 441).
Requirements
This component has the following requirements:
• Your core device must meet the requirements to run Lambda functions. If you want the core device
to run containerized Lambda functions, the device must meet the requirements to do so. For more
information, see Lambda function requirements (p. 64).
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 258) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.2.1
The following table lists the dependencies for version 2.2.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.6.0 Soft
2.2.0
The following table lists the dependencies for version 2.2.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.5.0 <2.6.0 Soft
2.1.3 and 2.1.4
The following table lists the dependencies for versions 2.1.3 and 2.1.4 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Soft
2.1.2
The following table lists the dependencies for version 2.1.2 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Soft
256
AWS IoT Greengrass Developer Guide, Version 2
Configuration
2.1.1
The following table lists the dependencies for version 2.1.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Soft
2.1.0
The following table lists the dependencies for version 2.1.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.2.0 Soft
2.0.x
The following table lists the dependencies for version 2.0.x of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.3 <2.1.0 Soft
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
getResultTimeoutInSecond
(Optional) The maximum amount of time in seconds that Lambda functions can run before they
time out.
Default: 60
Local log file
This component uses the same log file as the Greengrass nucleus (p. 181) component.
/greengrass/v2/logs/greengrass.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 with the path to the AWS IoT Greengrass root folder.
257
AWS IoT Greengrass Developer Guide, Version 2
Changelog
sudo tail -f /greengrass/v2/logs/greengrass.log
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.2.1 Changes this component's Greengrass nucleus (p. 181) dependency version
constraints to fix a dependency resolution issue.
2.2.0 Bug fixes and improvements
• Fixes an issue where Lambda functions couldn't write logs after a restart.
• Fixes an issue where the legacy subscription router sends duplicate
messages when there are wildcards in the topic.
• Fixes an issue where non-pinned Lambda functions couldn't use the
Greengrass interprocess communication (IPC) library in the AWS IoT Device
SDK.
2.1.4 Bug fixes and improvements
• Fixes an issue that caused Lambda functions that use NodeJS runtimes to
process only one message.
• Version updated for Greengrass nucleus version 2.5.0 release.
2.1.3 Version updated for Greengrass nucleus version 2.4.0 release.
2.1.2 Version updated for Greengrass nucleus version 2.3.0 release.
2.1.1 Version updated for Greengrass nucleus version 2.2.0 release.
2.1.0 Version updated for Greengrass nucleus version 2.1.0 release.
2.0.3 Initial version.
Lambda runtimes
The Lambda runtimes component (aws.greengrass.LambdaRuntimes) provides the runtimes that
Greengrass core devices use to run AWS Lambda functions.
Note
When you deploy a Lambda function component to a core device, the deployment also includes
this component. For more information, see Run AWS Lambda functions (p. 523).
Topics
• Versions (p. 259)
• Type (p. 259)
• Operating system (p. 259)
• Requirements (p. 259)
• Dependencies (p. 259)
• Configuration (p. 259)
• Local log file (p. 259)
258
AWS IoT Greengrass Developer Guide, Version 2
Versions
• Changelog (p. 259)
Versions
This component has the following versions:
• 2.0.x
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
Operating system
This component can be installed on Linux core devices only.
Requirements
This component has the following requirements:
• Your core device must meet the requirements to run Lambda functions. If you want the core device
to run containerized Lambda functions, the device must meet the requirements to do so. For more
information, see Lambda function requirements (p. 64).
Dependencies
This component doesn't have any dependencies.
Configuration
This component doesn't have any configuration parameters.
Local log file
This component doesn't output logs.
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.0.8 Version updated for Greengrass nucleus version 2.5.0 release.
2.0.7 Version updated for Greengrass nucleus version 2.4.0 release.
2.0.6 Version updated for Greengrass nucleus version 2.3.0 release.
259
AWS IoT Greengrass Developer Guide, Version 2
Legacy subscription router
Version Changes
2.0.5 Version updated for Greengrass nucleus version 2.2.0 release.
2.0.4 Version updated for Greengrass nucleus version 2.1.0 release.
2.0.3 Initial version.
Legacy subscription router
The legacy subscription router (aws.greengrass.LegacySubscriptionRouter) manages
subscriptions on the Greengrass core device. Subscriptions are a feature of AWS IoT Greengrass V1
that define the topics that Lambda functions can use for MQTT messaging on a core device. For more
information, see Managed subscriptions in the MQTT messaging workflow in the AWS IoT Greengrass V1
Developer Guide.
You can use this component to enable subscriptions for connector components and Lambda function
components that use the AWS IoT Greengrass Core SDK.
Note
This component is required only if your Lambda function uses the publish() function in the
AWS IoT Greengrass Core SDK. If you update your Lambda function code to use the interprocess
communication (IPC)s interface in the V2 AWS IoT Device SDK, you don't need to deploy the
legacy subscription router component. For more information, see the following interprocess
communication (p. 545) services:
• Publish/subscribe local messages (p. 561)
• Publish/subscribe AWS IoT Core MQTT messages (p. 586)
Topics
• Versions (p. 260)
• Type (p. 260)
• Operating system (p. 261)
• Dependencies (p. 261)
• Configuration (p. 262)
• Local log file (p. 265)
• Changelog (p. 265)
Versions
This component has the following versions:
• 2.1.x
• 2.0.x
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
260
AWS IoT Greengrass Developer Guide, Version 2
Operating system
Operating system
This component can be installed on Linux core devices only.
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 265) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.1.4
The following table lists the dependencies for version 2.1.4 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.6.0 Soft
2.1.3
The following table lists the dependencies for version 2.1.3 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Soft
2.1.2
The following table lists the dependencies for version 2.1.2 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Soft
2.1.1
The following table lists the dependencies for version 2.1.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Soft
2.1.0
The following table lists the dependencies for version 2.1.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.2.0 Soft
261
AWS IoT Greengrass Developer Guide, Version 2
Configuration
2.0.3
The following table lists the dependencies for version 2.0.3 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.3 <2.1.0 Soft
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
v2.1.x
subscriptions
(Optional) The subscriptions to enable on the core device. This is an object, where each key is a
unique ID, and each value is an object that defines the subscription for that connector. You must
configure a subscription when you deploy a V1 connector component or a Lambda function that
uses the AWS IoT Greengrass Core SDK.
Each subscription object contains the following information:
id
The unique ID of this subscription. This ID must match the key for this subscription object.
source
The Lambda function that uses the AWS IoT Greengrass Core SDK to publish MQTT
messages on the topics that you specify in subject. Specify one of the following:
• The name of a Lambda function component on the core device.
Specify the component name with the component: prefix, such as
component:com.example.HelloWorldLambda.
• The Amazon Resource Name (ARN) of a Lambda function on the core device.
Important
If the version of the Lambda function changes, you must configure the
subscription with the new version of the function. Otherwise, this component
won't route the messages until the version matches the subscription.
You must specify an Amazon Resource Name (ARN) that includes the version of
the function to import. You can't use version aliases like $LATEST.
To deploy a subscription for a V1 connector component, specify the name of the
component or the ARN of the connector component's Lambda function.
subject
The MQTT topic or topic filter on which the source and target can publish and receive
messages. This value supports the + and # topic wildcards.
target
The target that receives the MQTT messages on the topics that you specify in subject. The
subscription specifies that the source function publishes MQTT messages to AWS IoT Core
or to a Lambda function on the core device. Specify one of the following:
262
AWS IoT Greengrass Developer Guide, Version 2
Configuration
• cloud. The source function publishes MQTT messages to AWS IoT Core.
• The name of a Lambda function component on the core device.
Specify the component name with the component: prefix, such as
component:com.example.HelloWorldLambda.
• The Amazon Resource Name (ARN) of a Lambda function on the core device.
Important
If the version of the Lambda function changes, you must configure the
subscription with the new version of the function. Otherwise, this component
won't route the messages until the version matches the subscription.
You must specify an Amazon Resource Name (ARN) that includes the version of
the function to import. You can't use version aliases like $LATEST.
Default: No subscriptions
Example Example configuration update (defining a subscription to AWS IoT Core)
The following example specifies that the com.example.HelloWorldLambda Lambda function
component publishes MQTT message to AWS IoT Core on the hello/world topic.
{
"subscriptions": {
"Greengrass_HelloWorld_to_cloud": {
"id": "Greengrass_HelloWorld_to_cloud",
"source": "component:com.example.HelloWorldLambda",
"subject": "hello/world",
"target": "cloud"
}
}
}
Example Example configuration update (defining a subscription to another Lambda
function)
The following example specifies that the com.example.HelloWorldLambda Lambda function
component publishes MQTT messages to the com.example.MessageRelay Lambda function
component on the hello/world topic.
{
"subscriptions": {
"Greengrass_HelloWorld_to_MessageRelay": {
"id": "Greengrass_HelloWorld_to_MessageRelay",
"source": "component:com.example.HelloWorldLambda",
"subject": "hello/world",
"target": "component:com.example.MessageRelay"
}
}
}
v2.0.x
subscriptions
(Optional) The subscriptions to enable on the core device. This is an object, where each key is a
unique ID, and each value is an object that defines the subscription for that connector. You must
configure a subscription when you deploy a V1 connector component or a Lambda function that
uses the AWS IoT Greengrass Core SDK.
Each subscription object contains the following information:
263
AWS IoT Greengrass Developer Guide, Version 2
Configuration
id
The unique ID of this subscription. This ID must match the key for this subscription object.
source
The Lambda function that uses the AWS IoT Greengrass Core SDK to publish MQTT
messages on the topics that you specify in subject. Specify the following:
• The Amazon Resource Name (ARN) of a Lambda function on the core device.
Important
If the version of the Lambda function changes, you must configure the
subscription with the new version of the function. Otherwise, this component
won't route the messages until the version matches the subscription.
You must specify an Amazon Resource Name (ARN) that includes the version of
the function to import. You can't use version aliases like $LATEST.
To deploy a subscription for a V1 connector component, specify the ARN of the connector
component's Lambda function.
subject
The MQTT topic or topic filter on which the source and target can publish and receive
messages. This value supports the + and # topic wildcards.
target
The target that receives the MQTT messages on the topics that you specify in subject. The
subscription specifies that the source function publishes MQTT messages to AWS IoT Core
or to a Lambda function on the core device. Specify one of the following:
• cloud. The source function publishes MQTT messages to AWS IoT Core.
• The Amazon Resource Name (ARN) of a Lambda function on the core device.
Important
If the version of the Lambda function changes, you must configure the
subscription with the new version of the function. Otherwise, this component
won't route the messages until the version matches the subscription.
You must specify an Amazon Resource Name (ARN) that includes the version of
the function to import. You can't use version aliases like $LATEST.
Default: No subscriptions
Example Example configuration update (defining a subscription to AWS IoT Core)
The following example specifies that the Greengrass_HelloWorld function publishes MQTT
message to AWS IoT Core on the hello/world topic.
"subscriptions": {
"Greengrass_HelloWorld_to_cloud": {
"id": "Greengrass_HelloWorld_to_cloud",
"source": "arn:aws:lambda:us-west-2:123456789012:function:Greengrass_HelloWorld:5",
"subject": "hello/world",
"target": "cloud"
}
}
Example Example configuration update (defining a subscription to another Lambda
function)
The following example specifies that the Greengrass_HelloWorld function publishes MQTT
messages to the Greengrass_MessageRelay on the hello/world topic.
264
AWS IoT Greengrass Developer Guide, Version 2
Local log file
"subscriptions": {
"Greengrass_HelloWorld_to_MessageRelay": {
"id": "Greengrass_HelloWorld_to_MessageRelay",
"source": "arn:aws:lambda:us-west-2:123456789012:function:Greengrass_HelloWorld:5",
"subject": "hello/world",
"target": "arn:aws:lambda:us-
west-2:123456789012:function:Greengrass_MessageRelay:5"
}
}
Local log file
This component doesn't output logs.
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.1.4 Version updated for Greengrass nucleus version 2.5.0 release.
2.1.3 Version updated for Greengrass nucleus version 2.4.0 release.
2.1.2 Version updated for Greengrass nucleus version 2.3.0 release.
2.1.1 Version updated for Greengrass nucleus version 2.2.0 release.
2.1.0 Bug fixes and improvements
• Adds support to specify component names instead of ARNs for source
and target. If you specify a component name for a subscription, you don't
need to reconfigure the subscription each time the version of the Lambda
function changes.
2.0.3 Initial version.
Local debug console
The local debug console component (aws.greengrass.LocalDebugConsole) provides a local
dashboard that displays information about your AWS IoT Greengrass core devices and its components.
You can use this dashboard to debug your core device and manage local components.
Important
We recommend that you use this component in only development environments, not production
environments. This component provides access to information and operations that you typically
won't need in a production environment. Follow the principle of least privilege by deploying this
component to only core devices where you need it.
Topics
• Versions (p. 266)
• Type (p. 266)
• Operating system (p. 266)
• Requirements (p. 266)
265
AWS IoT Greengrass Developer Guide, Version 2
Versions
• Dependencies (p. 266)
• Configuration (p. 268)
• Usage (p. 269)
• Local log file (p. 272)
• Changelog (p. 273)
Versions
This component has the following versions:
• 2.2.x
• 2.1.x
• 2.0.x
Type
This component is a plugin component (aws.greengrass.plugin). The Greengrass nucleus (p. 181)
runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when
you change this component's version on the core device.
This component uses the same log file as the Greengrass nucleus. For more information, see Monitor
AWS IoT Greengrass logs (p. 506).
For more information, see Component types (p. 441).
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
Requirements
This component has the following requirements:
• You use a user name and password to sign in to the dashboard. The username, which is debug,
is provided for you. You must use the AWS IoT Greengrass CLI to create a temporary password
that authenticates you with the dashboard on a core device. You must be able to use the AWS
IoT Greengrass CLI to use the local debug console. For more information, see the Greengrass CLI
requirements (p. 226). For more information about how to generate the password and sign in, see
Local debug console component usage (p. 269).
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 273) of this component and the semantic version constraints that define the component
266
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.2.3
The following table lists the dependencies for version 2.2.3 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.1.0 <2.6.0 Hard
Greengrass CLI (p. 225) >=2.1.0 <2.6.0 Hard
2.2.2
The following table lists the dependencies for version 2.2.2 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.1.0 <2.5.0 Hard
Greengrass CLI (p. 225) >=2.1.0 <2.5.0 Hard
2.2.1
The following table lists the dependencies for version 2.2.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.1.0 <2.4.0 Hard
Greengrass CLI (p. 225) >=2.1.0 <2.4.0 Hard
2.2.0
The following table lists the dependencies for version 2.2.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.1.0 <2.3.0 Hard
Greengrass CLI (p. 225) >=2.1.0 <2.3.0 Hard
2.1.0
The following table lists the dependencies for version 2.1.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.1.0 <2.2.0 Hard
Greengrass CLI (p. 225) >=2.1.0 <2.2.0 Hard
267
AWS IoT Greengrass Developer Guide, Version 2
Configuration
2.0.x
The following table lists the dependencies for version 2.0.x of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.3 <2.1.0 Soft
Greengrass CLI (p. 225) >=2.0.3 <2.1.0 Soft
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
v2.1.x - v2.2.x
httpsEnabled
(Optional) You can enable HTTPS communication for the local debug console. If you enable
HTTPS communication, the local debug console creates a self-signed certificate. Web
browsers show security warnings for websites that use self-signed certificates, so you must
manually verify the certificate. Then, you can bypass the warning. For more information, see
Usage (p. 269).
Default: true
port
(Optional) The port at which to provide the local debug console.
Default: 1441
websocketPort
(Optional) The websocket port to use for the local debug console.
Default: 1442
bindHostname
(Optional) The hostname to use for the local debug console.
If you run the AWS IoT Greengrass Core software in a Docker container (p. 131), set this
parameter to 0.0.0.0, so you can open the local debug console outside the Docker container.
Default: localhost
Example Example: Configuration merge update
The following example configuration specifies to open the local debug console on non-default ports
and disable HTTPS.
{
"httpsEnabled": false,
"port": "10441",
"websocketPort": "10442"
268
AWS IoT Greengrass Developer Guide, Version 2
Usage
v2.0.x
port
(Optional) The port at which to provide the local debug console.
Default: 1441
websocketPort
(Optional) The websocket port to use for the local debug console.
Default: 1442
bindHostname
(Optional) The hostname to use for the local debug console.
If you run the AWS IoT Greengrass Core software in a Docker container (p. 131), set this
parameter to 0.0.0.0, so you can open the local debug console outside the Docker container.
Default: localhost
Example Example: Configuration merge update
The following example configuration specifies to open the local debug console on non-default ports.
{
"port": "10441",
"websocketPort": "10442"
}
Usage
To use the local debug console, create a session from the Greengrass CLI. When you create a session, the
Greengrass CLI provides a user name and temporary password that you can use to sign in to the local
debug console.
Follow these instructions to open the local debug console on your core device or on your development
computer.
v2.1.x - v2.2.x
In versions 2.1.0 and later, the local debug console uses HTTPS by default. When HTTPS is enabled,
the local debug console creates a self-signed certificate to secure the connection. Your web browser
shows a security warning when you open the local debug console because of this self-signed
certificate. When you create a session with the Greengrass CLI, the output includes the certificate's
fingerprints, so you can verify that the certificate is legitimate and the connection is secure.
You can disable HTTPS. For more information, see Local debug console configuration (p. 268).
To open the local debug console
1. (Optional) To view the local debug console on your development computer, you can forward the
console's port over SSH. However, you must first enable the AllowTcpForwarding option in
your core device's SSH configuration file. This option is enabled by default. Run the following
269
AWS IoT Greengrass Developer Guide, Version 2
Usage
command on your development computer to view the dashboard at http://localhost:1441
on your development computer.
ssh -L 1441:localhost:1441 -L 1442:localhost:1442 username@core-device-ip-address
Note
You can change the default ports from 1441 and 1442. For more information, see Local
debug console configuration (p. 268).
2. Create a session to use the local debug console. When you create a session, you generate a
password that you use to authenticate. The local debug console requires a password to increase
security, because you can use this component to view important information and perform
operations on the core device. The local debug console also creates a certificate to secure the
connection if you enable HTTPS in the component configuration. HTTPS is enabled by default.
Use the AWS IoT Greengrass CLI to create the session. This command generates a random 43-
character password that expires after 8 hours. Replace /greengrass/v2 or C:\greengrass
\v2 with the path to the AWS IoT Greengrass V2 root folder.
Linux or Unix
sudo /greengrass/v2/bin/greengrass-cli get-debug-password
Windows
C:\greengrass\v2\bin\greengrass-cli get-debug-password
The command output looks like the following example if you have configured the local debug
console to use HTTPS. You use the certificate fingerprints to verify that the connection is secure
when you open the local debug console.
Username: debug
Password: bEDp3MOHdj8ou2w5de_sCBI2XAaguy3a8XxREXAMPLE
Password expires at: 2021-04-01T17:01:43.921999931-07:00
The local debug console is configured to use TLS security. The certificate is self-
signed so you will need to bypass your web browser's security warnings to open the
console.
Before you bypass the security warning, verify that the certificate fingerprint
matches the following fingerprints.
SHA-256: 15 0B 2C E2 54 8B 22 DE 08 46 54 8A B1 2B 25 DE FB 02 7D 01 4E 4A 56 67 96
DA A6 CC B1 D2 C4 1B
SHA-1: BC 3E 16 04 D3 80 70 DA E0 47 25 F9 90 FA D6 02 80 3E B5 C1
The debug view component creates a session that lasts for 8 hours. After that, you must
generate a new password to view the local debug console again.
3. Open and sign in to the dashboard. View the dashboard on your Greengrass core device, or on
your development computer if you forward the port over SSH. Do one of the following:
• If you enabled HTTPS in the local debug console, which is the default setting, do the
following:
a. Open https://localhost:1441 on your core device, or on your development
computer if you forwarded the port over SSH.
Your browser might show a security warning about an invalid security certificate.
b. If your browser shows a security warning, verify the certificate is legitimate and bypass
the security warning. Do the following:
270
AWS IoT Greengrass Developer Guide, Version 2
Usage
i. Find the SHA-256 or SHA-1 fingerprint for the certificate, and verify that it
matches the SHA-256 or SHA-1 fingerprint that the get-debug-password
command previously printed. Your browser might provide one or both fingerprints.
Consult your browser's documentation to view the certificate and its fingerprints.
In some browsers, the certificate fingerprint is called a thumbprint.
Note
If the certificate fingerprint doesn't match, go to Step 2 (p. 270) to
create a new session. If the certificate fingerprint still doesn't match, your
connection might be insecure.
ii. If the certificate fingerprint matches, bypass your browser's security warning to
open the local debug console. Consult your browser's documentation to bypass the
browser security warning.
c. Sign in to the website using the user name and password that the get-debug-
password command printed earlier.
The local debug console opens.
d. If the local debug console shows an error that says it can't connect to the WebSocket
due to a failed TLS handshake, you must bypass the self-signed security warning for
the WebSocket URL.
Do the following:
i. Open https://localhost:1442 in the same browser where you opened the
local debug console.
ii. Verify the certificate and bypass the security warning.
Your browser might show an HTTP 404 page after you bypass the warning.
iii. Open https://localhost:1441 again.
The local debug console shows information about the core device.
• If you disabled HTTPS in the local debug console, do the following:
a. Open http://localhost:1441 on your core device, or open it on your development
computer if you forwarded the port over SSH.
b. Sign in to the website using the user name and password that the get-debug-
password command previously printed.
The local debug console opens.
v2.0.x
To open the local debug console
1. (Optional) To view the local debug console on your development computer, you can forward the
console's port over SSH. However, you must first enable the AllowTcpForwarding option in
your core device's SSH configuration file. This option is enabled by default. Run the following
command on your development computer to view the dashboard at http://localhost:1441
on your development computer.
271
AWS IoT Greengrass Developer Guide, Version 2
Local log file
ssh -L 1441:localhost:1441 -L 1442:localhost:1442 username@core-device-ip-address
Note
You can change the default ports from 1441 and 1442. For more information, see Local
debug console configuration (p. 268).
2. Create a session to use the local debug console. When you create a session, you generate a
password that you use to authenticate. The local debug console requires a password to increase
security, because you can use this component to view important information and perform
operations on the core device.
Use the AWS IoT Greengrass CLI to create the session. This command generates a random 43-
character password that expires after 8 hours. Replace /greengrass/v2 or C:\greengrass
\v2 with the path to the AWS IoT Greengrass V2 root folder.
Linux or Unix
sudo /greengrass/v2/bin/greengrass-cli get-debug-password
Windows
C:\greengrass\v2\bin\greengrass-cli get-debug-password
The command output looks like the following example.
Username: debug
Password: bEDp3MOHdj8ou2w5de_sCBI2XAaguy3a8XxREXAMPLE
Password will expire at: 2021-04-01T17:01:43.921999931-07:00
The debug view component creates a session lasts for 4 hours, and then you must generate a
new password to view the local debug console again.
3. Open http://localhost:1441 on your core device, or open it on your development
computer if you forwarded the port over SSH.
4. Sign in to the website using the user name and password that the get-debug-password
command previously printed.
The local debug console opens.
Local log file
This component uses the same log file as the Greengrass nucleus (p. 181) component.
Linux
/greengrass/v2/logs/greengrass.log
Windows
C:\greengrass\v2\logs\greengrass.log
272
AWS IoT Greengrass Developer Guide, Version 2
Changelog
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
Linux
sudo tail -f /greengrass/v2/logs/greengrass.log
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.2.3 Bug fixes and improvements
• Fixes an issue that prevented startup when the component couldn't
decrypt the keystore that holds the SSL private key.
• Version updated for Greengrass nucleus version 2.5.0 release.
2.2.2 Version updated for Greengrass nucleus version 2.4.0 release.
2.2.1 Version updated for Greengrass nucleus version 2.3.0 release.
2.2.0 Version updated for Greengrass nucleus version 2.2.0 release.
2.1.0 New features
• Uses HTTPS to secure your connection to the local debug console. HTTPS is
enabled by default.
Bug fixes and improvements
• You can dismiss flashbar messages in the configuration editor.
2.0.3 Initial version.
Log manager
The log manager component (aws.greengrass.LogManager) uploads logs from AWS IoT Greengrass
core devices to Amazon CloudWatch Logs. You can upload logs from the Greengrass nucleus, other
Greengrass components, and other applications and services that aren't Greengrass components. For
more information about how to monitor logs in CloudWatch Logs and on the local file system, see
Monitor AWS IoT Greengrass logs (p. 506).
The following considerations apply when you use the log manager component to write to CloudWatch
Logs:
• Log delays
273
AWS IoT Greengrass Developer Guide, Version 2
Versions
The log manager component writes logs from only rotated log files. By default, the AWS IoT
Greengrass Core software rotates log files every hour or after they are 1,024 KB. As a result, the log
manager component uploads logs only after the AWS IoT Greengrass Core software or a Greengrass
component writes over 1,024 KB worth of logs. You can configure a lower log file size limit to cause
log files to rotate more often. This causes the log manager component to upload logs to CloudWatch
Logs more frequently.
The log manager component also uploads new logs periodically. By default, the log manager
component uploads new logs every 5 minutes. You can configure a lower upload interval, so the log
manager component uploads logs to CloudWatch Logs more frequently.
If you need to observe logs in real time, consider using file system logs (p. 507).
• Clock skew
The log manager component uses the standard Signature Version 4 signing process to create API
requests to CloudWatch Logs. If the system time on a core device is out of sync by more than 15
minutes, then CloudWatch Logs rejects the requests. For more information, see Signature Version 4
signing process in the AWS General Reference.
For information about the log groups and log streams to which this component uploads logs, see
Usage (p. 285).
Topics
• Versions (p. 274)
• Type (p. 274)
• Operating system (p. 275)
• Requirements (p. 275)
• Dependencies (p. 276)
• Configuration (p. 277)
• Usage (p. 285)
• Local log file (p. 287)
• Changelog (p. 287)
Versions
This component has the following versions:
• 2.2.x
• 2.1.x
• 2.0.x
Type
This component is a plugin component (aws.greengrass.plugin). The Greengrass nucleus (p. 181)
runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when
you change this component's version on the core device.
This component uses the same log file as the Greengrass nucleus. For more information, see Monitor
AWS IoT Greengrass logs (p. 506).
For more information, see Component types (p. 441).
274
AWS IoT Greengrass Developer Guide, Version 2
Operating system
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
Requirements
This component has the following requirements:
• The Greengrass device role (p. 790) must allow the logs:CreateLogGroup,
logs:CreateLogStream, logs:PutLogEvents, and logs:DescribeLogStreams actions, as
shown in the following example IAM policy.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:DescribeLogStreams"
],
"Effect": "Allow",
"Resource": "arn:aws:logs:*:*:*"
}
]
}
Note
The Greengrass device role (p. 790) that you create when you install the AWS IoT Greengrass
Core software includes the permissions in this example policy by default.
For more information, see Using identity-based policies (IAM policies) for CloudWatch Logs in the
Amazon CloudWatch Logs User Guide.
Endpoints and ports
This component must be able to perform outbound requests to the following endpoints and ports, in
addition to endpoints and ports required for basic operation. For more information, see Allow device
traffic through a proxy or firewall (p. 807).
Endpoint Port Required Description
logs.region.amazonaws.com 443 No Required if
you write
logs to
CloudWatch
Logs.
275
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 287) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.2.1
The following table lists the dependencies for version 2.2.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.1.0 <2.6.0 Soft
2.1.3 and 2.2.0
The following table lists the dependencies for versions 2.1.3 and 2.2.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.1.0 <2.5.0 Soft
2.1.2
The following table lists the dependencies for version 2.1.2 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.1.0 <2.4.0 Soft
2.1.1
The following table lists the dependencies for version 2.1.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.1.0 <2.3.0 Soft
2.1.0
The following table lists the dependencies for version 2.1.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.1.0 <2.2.0 Soft
2.0.x
The following table lists the dependencies for version 2.0.x of this component.
276
AWS IoT Greengrass Developer Guide, Version 2
Configuration
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.3 <2.1.0 Soft
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
v2.2.x
logsUploaderConfiguration
(Optional) The configuration for logs that the log manager component uploads. This object
contains the following information:
systemLogsConfiguration
(Optional) The configuration for AWS IoT Greengrass Core software system logs, which
include logs from the Greengrass nucleus (p. 181) and plugin components (p. 441).
Specify this configuration to enable the log manager component to manage system logs.
This object contains the following information:
uploadToCloudWatch
(Optional) You can upload system logs to CloudWatch Logs.
Default: false
minimumLogLevel
(Optional) The minimum level of log messages to upload. This minimum level applies
only if you configure the Greengrass nucleus component (p. 181) to output JSON
format logs. To enable JSON format logs, specify JSON for the logging format (p. 186)
parameter (logging.format).
Choose from the following log levels, listed here in level order:
• DEBUG
• INFO
• WARN
• ERROR
Default: INFO
diskSpaceLimit
(Optional) The maximum total size of Greengrass system log files, in the unit you
specify in diskSpaceLimitUnit. After the total size of Greengrass system log files
exceeds this maximum total size, the AWS IoT Greengrass Core software deletes the
oldest Greengrass system log files.
This parameter is equivalent to the log size limit (p. 187) parameter
(totalLogsSizeKB) of the Greengrass nucleus component (p. 181). The AWS IoT
Greengrass Core software uses the minimum of the two values as the maximum total
Greengrass system log size.
diskSpaceLimitUnit
(Optional) The unit for the diskSpaceLimit. Choose from the following options:
277
AWS IoT Greengrass Developer Guide, Version 2
Configuration
• KB – kilobytes
• MB – megabytes
• GB – gigabytes
Default: KB
deleteLogFileAfterCloudUpload
(Optional) You can delete a log file after the log manager component uploads the logs
to CloudWatch Logs.
Default: false
componentLogsConfigurationMap
(Optional) A map of log configurations for components on the core device. Each
componentName object in this map defines the log configuration for the component or
application. The log manager component uploads these component logs to CloudWatch
Logs.
Note
If you're upgrading from a version of log manager earlier than v2.2.0, you
can continue to use the componentLogsConfiguration list instead of
componentLogsConfigurationMap. However, we strongly recommend
that you use the map format so that you can use merge and reset updates
to modify configurations for specific components. For information about the
componentLogsConfiguration parameter, see the configuration parameters for
v2.1.x of this component.
componentName
The log configuration for the componentName component or application for this log
configuration. You can specify the name of a Greengrass component or another value
to identify this log group.
Each object contains the following information:
minimumLogLevel
(Optional) The minimum level of log messages to upload. This minimum level
applies only if this component's logs use a specific JSON format, which you can find
in the AWS IoT Greengrass logging module repository on GitHub.
Choose from the following log levels, listed here in level order:
• DEBUG
• INFO
• WARN
• ERROR
Default: INFO
logFileDirectoryPath
(Optional) The path to the folder that contains this component's log files.
You don't need to specify this parameter for Greengrass components that print to
standard output (stdout) and standard error (stderr).
Default: /greengrass/v2/logs.
logFileRegex
(Optional) A regular expression that specifies the log file name format that the
component or application uses. The log manager component uses this regular
expression to identify log files in the folder at logFileDirectoryPath.
278
AWS IoT Greengrass Developer Guide, Version 2
Configuration
You don't need to specify this parameter for Greengrass components that print to
standard output (stdout) and standard error (stderr).
If your component or application rotates log files, specify a regex that matches the
rotated log file names. For example, you might specify hello_world\\w*.log
to upload logs for a Hello World application. The \\w* pattern matches zero or
more word characters, which includes alphanumeric characters and underscores.
This regex matches log files with and without timestamps in their name. In this
example, the log manager uploads the following log files:
• hello_world.log – The most recent log file for the Hello World application.
• hello_world_2020_12_15_17_0.log – An older log file for the Hello World
application.
Default: componentName\\w*.log, where componentName is the name of the
component for this log configuration.
diskSpaceLimit
(Optional) The maximum total size of all log files for this component, in the unit
you specify in diskSpaceLimitUnit. After the total size of this component's
log files exceeds this maximum total size, the AWS IoT Greengrass Core software
deletes this component's oldest log files.
This parameter is related to the log size limit (p. 187) parameter
(totalLogsSizeKB) of the Greengrass nucleus component (p. 181). The AWS
IoT Greengrass Core software uses the minimum of the two values as the maximum
total log size for this component.
diskSpaceLimitUnit
(Optional) The unit for the diskSpaceLimit. Choose from the following options:
• KB – kilobytes
• MB – megabytes
• GB – gigabytes
Default: KB
deleteLogFileAfterCloudUpload
(Optional) You can delete a log file after the log manager component uploads the
logs to CloudWatch Logs.
Default: false
periodicUploadIntervalSec
(Optional) The period in seconds at which the log manager component checks for new log files
to upload.
Default: 300 (5 minutes)
Example Example: Configuration merge update
The following example configuration specifies to upload system logs and
com.example.HelloWorld component logs to CloudWatch Logs.
{
"logsUploaderConfiguration": {
"systemLogsConfiguration": {
"uploadToCloudWatch": "true",
"minimumLogLevel": "INFO",
"diskSpaceLimit": "10",
279
AWS IoT Greengrass Developer Guide, Version 2
Configuration
"diskSpaceLimitUnit": "MB",
"deleteLogFileAfterCloudUpload": "false"
},
"componentLogsConfiguration": {
"com.example.HelloWorld": {
"minimumLogLevel": "INFO",
"diskSpaceLimit": "10",
"diskSpaceLimitUnit": "KB",
"deleteLogFileAfterCloudUpload": "false"
}
}
},
"periodicUploadIntervalSec": "300"
}
v2.1.x
logsUploaderConfiguration
(Optional) The configuration for logs that the log manager component uploads. This object
contains the following information:
systemLogsConfiguration
(Optional) The configuration for AWS IoT Greengrass Core software system logs, which
include logs from the Greengrass nucleus (p. 181) and plugin components (p. 441).
Specify this configuration to enable the log manager component to manage system logs.
This object contains the following information:
uploadToCloudWatch
(Optional) You can upload system logs to CloudWatch Logs.
Default: false
minimumLogLevel
(Optional) The minimum level of log messages to upload. This minimum level applies
only if you configure the Greengrass nucleus component (p. 181) to output JSON
format logs. To enable JSON format logs, specify JSON for the logging format (p. 186)
parameter (logging.format).
Choose from the following log levels, listed here in level order:
• DEBUG
• INFO
• WARN
• ERROR
Default: INFO
diskSpaceLimit
(Optional) The maximum total size of Greengrass system log files, in the unit you
specify in diskSpaceLimitUnit. After the total size of Greengrass system log files
exceeds this maximum total size, the AWS IoT Greengrass Core software deletes the
oldest Greengrass system log files.
This parameter is equivalent to the log size limit (p. 187) parameter
(totalLogsSizeKB) of the Greengrass nucleus component (p. 181). The AWS IoT
Greengrass Core software uses the minimum of the two values as the maximum total
Greengrass system log size.
diskSpaceLimitUnit
(Optional) The unit for the diskSpaceLimit. Choose from the following options:
280
AWS IoT Greengrass Developer Guide, Version 2
Configuration
• KB – kilobytes
• MB – megabytes
• GB – gigabytes
Default: KB
deleteLogFileAfterCloudUpload
(Optional) You can delete a log file after the log manager component uploads the logs
to CloudWatch Logs.
Default: false
componentLogsConfiguration
(Optional) A list of log configurations for components on the core device. Each
configuration in this list defines the log configuration for a component or application. The
log manager component uploads these component logs to CloudWatch Logs
Each object contains the following information:
componentName
The name of the component or application for this log configuration. You can specify
the name of a Greengrass component or another value to identify this log group.
minimumLogLevel
(Optional) The minimum level of log messages to upload. This minimum level applies
only if this component's logs use a specific JSON format, which you can find in the AWS
IoT Greengrass logging module repository on GitHub.
Choose from the following log levels, listed here in level order:
• DEBUG
• INFO
• WARN
• ERROR
Default: INFO
logFileDirectoryPath
(Optional) The path to the folder that contains this component's log files.
You don't need to specify this parameter for Greengrass components that print to
standard output (stdout) and standard error (stderr).
Default: /greengrass/v2/logs.
logFileRegex
(Optional) A regular expression that specifies the log file name format that the
component or application uses. The log manager component uses this regular
expression to identify log files in the folder at logFileDirectoryPath.
You don't need to specify this parameter for Greengrass components that print to
standard output (stdout) and standard error (stderr).
If your component or application rotates log files, specify a regex that matches the
rotated log file names. For example, you might specify hello_world\\w*.log to
upload logs for a Hello World application. The \\w* pattern matches zero or more
word characters, which includes alphanumeric characters and underscores. This regex
matches log files with and without timestamps in their name. In this example, the log
manager uploads the following log files:
• hello_world.log – The most recent log file for the Hello World application.
281
AWS IoT Greengrass Developer Guide, Version 2
Configuration
• hello_world_2020_12_15_17_0.log – An older log file for the Hello World
application.
Default: componentName\\w*.log, where componentName is the name of the
component for this log configuration.
diskSpaceLimit
(Optional) The maximum total size of all log files for this component, in the unit you
specify in diskSpaceLimitUnit. After the total size of this component's log files
exceeds this maximum total size, the AWS IoT Greengrass Core software deletes this
component's oldest log files.
This parameter is related to the log size limit (p. 187) parameter (totalLogsSizeKB)
of the Greengrass nucleus component (p. 181). The AWS IoT Greengrass Core
software uses the minimum of the two values as the maximum total log size for this
component.
diskSpaceLimitUnit
(Optional) The unit for the diskSpaceLimit. Choose from the following options:
• KB – kilobytes
• MB – megabytes
• GB – gigabytes
Default: KB
deleteLogFileAfterCloudUpload
(Optional) You can delete a log file after the log manager component uploads the logs
to CloudWatch Logs.
Default: false
periodicUploadIntervalSec
(Optional) The period in seconds at which the log manager component checks for new log files
to upload.
Default: 300 (5 minutes)
Example Example: Configuration merge update
The following example configuration specifies to upload system logs and
com.example.HelloWorld component logs to CloudWatch Logs.
{
"logsUploaderConfiguration": {
"systemLogsConfiguration": {
"uploadToCloudWatch": "true",
"minimumLogLevel": "INFO",
"diskSpaceLimit": "10",
"diskSpaceLimitUnit": "MB",
"deleteLogFileAfterCloudUpload": "false"
},
"componentLogsConfiguration": [
{
"componentName": "com.example.HelloWorld",
"minimumLogLevel": "INFO",
"diskSpaceLimit": "10",
"diskSpaceLimitUnit": "KB",
"deleteLogFileAfterCloudUpload": "false"
}
282
AWS IoT Greengrass Developer Guide, Version 2
Configuration
]
},
"periodicUploadIntervalSec": "300"
}
v2.0.x
logsUploaderConfiguration
(Optional) The configuration for logs that the log manager component uploads. This object
contains the following information:
systemLogsConfiguration
(Optional) The configuration for AWS IoT Greengrass Core software system logs. Specify
this configuration to enable the log manager component to manage system logs. This
object contains the following information:
uploadToCloudWatch
(Optional) You can upload system logs to CloudWatch Logs.
Default: false
minimumLogLevel
(Optional) The minimum level of log messages to upload. This minimum level applies
only if you configure the Greengrass nucleus component (p. 181) to output JSON
format logs. To enable JSON format logs, specify JSON for the logging format (p. 186)
parameter (logging.format).
Choose from the following log levels, listed here in level order:
• DEBUG
• INFO
• WARN
• ERROR
Default: INFO
diskSpaceLimit
(Optional) The maximum total size of Greengrass system log files, in the unit you
specify in diskSpaceLimitUnit. After the total size of Greengrass system log files
exceeds this maximum total size, the AWS IoT Greengrass Core software deletes the
oldest Greengrass system log files.
This parameter is equivalent to the log size limit (p. 187) parameter
(totalLogsSizeKB) of the Greengrass nucleus component (p. 181). The AWS IoT
Greengrass Core software uses the minimum of the two values as the maximum total
Greengrass system log size.
diskSpaceLimitUnit
(Optional) The unit for the diskSpaceLimit. Choose from the following options:
• KB – kilobytes
• MB – megabytes
• GB – gigabytes
Default: KB
deleteLogFileAfterCloudUpload
(Optional) You can delete a log file after the log manager component uploads the logs
to CloudWatch Logs.
283
AWS IoT Greengrass Developer Guide, Version 2
Configuration
Default: false
componentLogsConfiguration
(Optional) A list of log configurations for components on the core device. Each
configuration in this list defines the log configuration for a component or application. The
log manager component uploads these component logs to CloudWatch Logs
Each object contains the following information:
componentName
The name of the component or application for this log configuration. You can specify
the name of a Greengrass component or another value to identify this log group.
minimumLogLevel
(Optional) The minimum level of log messages to upload. This minimum level applies
only if this component's logs use a specific JSON format, which you can find in the AWS
IoT Greengrass logging module repository on GitHub.
Choose from the following log levels, listed here in level order:
• DEBUG
• INFO
• WARN
• ERROR
Default: INFO
logFileDirectoryPath
The path to the folder that contains this component's log files.
To upload a Greengrass component's logs, specify /greengrass/v2/logs, and
replace /greengrass/v2 with your Greengrass root folder.
logFileRegex
A regular expression that specifies the log file name format that the component or
application uses. The log manager component uses this regular expression to identify
log files in the folder at logFileDirectoryPath.
To upload a Greengrass component's logs, specify a regex that matches the rotated
log file names. For example, you might specify com.example.HelloWorld\\w*.log
to upload logs for a Hello World component. The \\w* pattern matches zero or more
word characters, which includes alphanumeric characters and underscores. This regex
matches log files with and without timestamps in their name. In this example, the log
manager uploads the following log files:
• com.example.HelloWorld.log – The most recent log file for the Hello World
component.
• com.example.HelloWorld_2020_12_15_17_0.log – An older log file for the
Hello World component. The Greengrass nucleus adds a rotating timestamp to the
log files.
diskSpaceLimit
(Optional) The maximum total size of all log files for this component, in the unit you
specify in diskSpaceLimitUnit. After the total size of this component's log files
exceeds this maximum total size, the AWS IoT Greengrass Core software deletes this
component's oldest log files.
284
AWS IoT Greengrass Developer Guide, Version 2
Usage
This parameter is related to the log size limit (p. 187) parameter (totalLogsSizeKB)
of the Greengrass nucleus component (p. 181). The AWS IoT Greengrass Core
software uses the minimum of the two values as the maximum total log size for this
component.
diskSpaceLimitUnit
(Optional) The unit for the diskSpaceLimit. Choose from the following options:
• KB – kilobytes
• MB – megabytes
• GB – gigabytes
Default: KB
deleteLogFileAfterCloudUpload
(Optional) You can delete a log file after the log manager component uploads the logs
to CloudWatch Logs.
Default: false
periodicUploadIntervalSec
(Optional) The period in seconds at which the log manager component checks for new log files
to upload.
Default: 300 (5 minutes)
Example Example: Configuration merge update
The following example configuration specifies to upload system logs and
com.example.HelloWorld component logs to CloudWatch Logs.
{
"logsUploaderConfiguration": {
"systemLogsConfiguration": {
"uploadToCloudWatch": "true",
"minimumLogLevel": "INFO",
"diskSpaceLimit": "10",
"diskSpaceLimitUnit": "MB",
"deleteLogFileAfterCloudUpload": "false"
},
"componentLogsConfiguration": [
{
"componentName": "com.example.HelloWorld",
"minimumLogLevel": "INFO",
"logFileDirectoryPath": "/greengrass/v2/logs",
"logFileRegex": "com.example.HelloWorld\\w*.log",
"diskSpaceLimit": "10",
"diskSpaceLimitUnit": "KB",
"deleteLogFileAfterCloudUpload": "false"
}
]
},
"periodicUploadIntervalSec": "300"
}
Usage
The log manager component uploads to the following log groups and log streams.
285
AWS IoT Greengrass Developer Guide, Version 2
Usage
2.1.x
Log group name
/aws/greengrass/componentType/region/componentName
The log group name uses the following variables:
• componentType – The type of the component, which can be one of the following:
• GreengrassSystemComponent – The component is part of the Greengrass
nucleus (p. 181). This log group includes logs for plugin components, which run in the
same JVM as the Greengrass nucleus.
• UserComponent – The component isn't part of the Greengrass nucleus. This log group
includes logs for generic components, Lambda components, and other applications on the
device.
For more information, see Component types (p. 441).
• region – The AWS Region that the core device uses.
• componentName – The name of the component. For system logs, this value is System.
Log stream name
/date/thing/thingName
The log stream name uses the following variables:
• date – The date of the log, such as 2020/12/15. The log manager component uses the
yyyy/MM/dd format.
• thingName – The name of the core device.
Note
If a thing name contains a colon (:), the log manager replaces the colon with a plus (+).
2.0.x
Log group name
/aws/greengrass/componentType/region/componentName
The log group name uses the following variables:
• componentType – The type of the component, which can be one of the following:
• GreengrassSystemComponent – The component is part of the Greengrass
nucleus (p. 181).
• UserComponent – The component isn't part of the Greengrass nucleus. The log manager
uses this type for Greengrass components and other applications on the device.
• region – The AWS Region that the core device uses.
• componentName – The name of the component. For system logs, this value is System.
Log stream name
/date/deploymentTargets/thingName
The log stream name uses the following variables:
• date – The date of the log, such as 2020/12/15. The log manager component uses the
yyyy/MM/dd format.
286
AWS IoT Greengrass Developer Guide, Version 2
Local log file
• deploymentTargets – The things whose deployments include the component. The log
manager component separates each target by a slash. If the component runs on the core
device as the result of a local deployment, this value is LOCAL_DEPLOYMENT.
Consider an example where you have a core device named MyGreengrassCore, and the core
device has two deployments:
• A deployment that targets the core device, MyGreengrassCore.
• A deployment that targets a thing group named MyGreengrassCoreGroup, which
contains the core device.
The deploymentTargets for this core device are thing/MyGreengrassCore/
thinggroup/MyGreengrassCoreGroup.
• thingName – The name of the core device.
Local log file
This component uses the same log file as the Greengrass nucleus (p. 181) component.
Linux
/greengrass/v2/logs/greengrass.log
Windows
C:\greengrass\v2\logs\greengrass.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
Linux
sudo tail -f /greengrass/v2/logs/greengrass.log
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.2.1 Version updated for Greengrass nucleus version 2.5.0 release.
2.2.0 New feature
• Adds the componentLogsConfigurationMap configuration parameter
to support a map format for component log configurations. Each
287
AWS IoT Greengrass Developer Guide, Version 2
Machine learning components
Version Changes
componentName object in the map defines the log configuration for a
component or application.
2.1.3 Version updated for Greengrass nucleus version 2.4.0 release.
2.1.2 Version updated for Greengrass nucleus version 2.3.0 release.
2.1.1 Bug fixes and improvements
• Fixes an issue where the system log configuration wasn't updated in certain
cases.
2.1.0 Bug fixes and improvements
• Use defaults for logFileDirectoryPath and logFileRegex that work
for Greengrass components that print to standard output (stdout) and
standard error (stderr).
• Correctly route traffic through a configured network proxy when uploading
logs to CloudWatch Logs.
• Correctly handle colon characters (:) in log stream names. CloudWatch
Logs log stream names don't support colons.
• Simplify log stream names by removing thing group names from the log
stream.
• Remove an error log message that prints during normal behavior.
2.0.x Initial version.
Machine learning components
AWS IoT Greengrass provides the following machine learning components that you can deploy to
supported devices to perform machine learning inference (p. 723) using models trained in Amazon
SageMaker or with your own pre-trained models that are stored in Amazon S3.
AWS-provided machine learning components are broadly categorized as follows:
• Model component—Contains machine learning models as Greengrass artifacts.
• Runtime component—Contains the script that installs the machine learning framework and its
dependencies on the Greengrass core device.
• Inference component—Contains the inference code and includes component dependencies to install
the machine learning framework and download pre-trained machine learning models.
You can use the sample inference code and pre-trained models in the AWS-provided machine learning
components to perform image classification and object detection using DLR and TensorFlow Lite. To
perform custom machine learning inference with your own models that are stored in Amazon S3, or
to use a different machine learning framework, you can use the recipes of these public components as
templates to create custom machine learning components. For more information, see Customize your
machine learning components (p. 746).
AWS IoT Greengrass also includes an AWS-provided component to manage the installation and lifecycle
of the SageMaker Edge Manager agent on Greengrass core devices. With SageMaker Edge Manager, you
can use Amazon SageMaker Neo-compiled models directly on your core device. For more information,
see Use Amazon SageMaker Edge Manager on Greengrass core devices (p. 738).
The following table lists the machine learning components that are available in AWS IoT Greengrass.
288
AWS IoT Greengrass Developer Guide, Version 2
Machine learning components
Note
Several AWS-provided components depend on specific minor versions of the Greengrass
nucleus. Because of this dependency, you need to update these components when you update
the Greengrass nucleus to a new minor version. For information about the specific versions
of the nucleus that each component depends on, see the corresponding component topic.
For more information about updating the nucleus, see Update the AWS IoT Greengrass Core
software (OTA) (p. 170).
Component Description Depends Component Supported Open
on type (p. 441)OS source (p. 921)
nucleus
SageMaker Edge Deploys the Yes Generic Linux, No
Manager (p. 292) Amazon Windows
SageMaker
Edge Manager
agent on the
Greengrass
core device.
DLR image Inference Yes Generic Linux, No
classification (p. 299) component Windows
that uses the
DLR image
classification
model store
and the DLR
runtime
component as
dependencies
to install DLR,
download
sample image
classification
models, and
perform
image
classification
inference on
supported
devices.
DLR object detection (p. 306) Inference Yes Generic Linux, No
component Windows
that uses the
DLR object
detection
model store
and the DLR
runtime
component as
dependencies
to install DLR,
download
sample object
detection
models, and
289
AWS IoT Greengrass Developer Guide, Version 2
Machine learning components
Component Description Depends Component Supported Open
on type (p. 441)OS source (p. 921)
nucleus
perform
object
detection
inference on
supported
devices.
DLR image classification model Model Yes Generic Linux, No
store (p. 313) component Windows
that contains
sample
ResNet-50
image
classification
models as
Greengrass
artifacts.
DLR object detection model Model Yes Generic Linux, No
store (p. 316) component Windows
that contains
sample
YOLOv3
object
detection
models as
Greengrass
artifacts.
DLR installer (p. 319) Runtime Yes Generic Linux, No
component Windows
that contains
an installation
script that is
used to install
DLR and its
dependencies
on the
Greengrass
core device.
290
AWS IoT Greengrass Developer Guide, Version 2
Machine learning components
Component Description Depends Component Supported Open
on type (p. 441)OS source (p. 921)
nucleus
TensorFlow Lite image Inference Yes Generic Linux, No
classification (p. 324) component Windows
that uses the
TensorFlow
Lite image
classification
model store
and the
TensorFlow
Lite runtime
component as
dependencies
to install
TensorFlow
Lite,
download
sample image
classification
models, and
perform
image
classification
inference on
supported
devices.
TensorFlow Lite object Inference Yes Generic Linux, No
detection (p. 329) component Windows
that uses the
TensorFlow
Lite object
detection
model store
and the
TensorFlow
Lite runtime
component as
dependencies
to install
TensorFlow
Lite,
download
sample object
detection
models, and
perform
object
detection
inference on
supported
devices.
291
AWS IoT Greengrass Developer Guide, Version 2
SageMaker Edge Manager
Component Description Depends Component Supported Open
on type (p. 441)OS source (p. 921)
nucleus
TensorFlow Lite image Model Yes Generic Linux, No
classification model component Windows
store (p. 334) that contains
a sample
MobileNet v1
model as a
Greengrass
artifact.
TensorFlow Lite object detection Model Yes Generic Linux, No
model store (p. 337) component Windows
that contains
a sample
Single Shot
Detection
(SSD)
MobileNet
model as a
Greengrass
artifact.
TensorFlow Lite Runtime Yes Generic Linux, No
installer (p. 339) component Windows
that contains
an installation
script that is
used to install
TensorFlow
Lite and its
dependencies
on the
Greengrass
core device.
SageMaker Edge Manager
The Amazon SageMaker Edge Manager component (aws.greengrass.SageMakerEdgeManager)
installs the SageMaker Edge Manager agent binary.
SageMaker Edge Manager provides model management for edge devices so you can optimize, secure,
monitor, and maintain machine learning models on fleets of edge devices. The SageMaker Edge Manager
component installs and manages the lifecycle of the SageMaker Edge Manager agent on your core
device. You can also use SageMaker Edge Manager to package and use SageMaker Neo-compiled models
as model components on Greengrass core devices. For more information about using SageMaker Edge
Manager agent on your core device, see Use Amazon SageMaker Edge Manager on Greengrass core
devices (p. 738).
SageMaker Edge Manager component v1.1.x installs Edge Manager agent binary v1.20210820.e20fa3a.
For more information about Edge Manager agent binary versions, see Edge Manager Agent.
Note
The SageMaker Edge Manager component is available only in the following AWS Regions:
292
AWS IoT Greengrass Developer Guide, Version 2
SageMaker Edge Manager
• US East (Ohio)
• US East (N. Virginia)
• US West (Oregon)
• EU (Frankfurt)
• EU (Ireland)
• Asia Pacific (Tokyo)
Topics
• Versions (p. 293)
• Type (p. 293)
• Operating system (p. 293)
• Requirements (p. 293)
• Dependencies (p. 295)
• Configuration (p. 296)
• Local log file (p. 298)
• Changelog (p. 299)
Versions
This component has the following versions:
• 1.1.x
• 1.0.x
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
Requirements
This component has the following requirements:
• A Greengrass core device running on Amazon Linux 2, a Debian-based Linux platform (x86_64 or
Armv8), or Windows (x86_64). If you don't have one, see Getting started with AWS IoT Greengrass
V2 (p. 31).
• Python 3.6 or later, including pip for your version of Python, installed on your core device.
• The Greengrass device role (p. 790) configured with the following:
• A trust relationship that allows credentials.iot.amazonaws.com and
sagemaker.amazonaws.com to assume the role, as shown in the following IAM policy example.
293
AWS IoT Greengrass Developer Guide, Version 2
SageMaker Edge Manager
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "credentials.iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
},
{
"Effect": "Allow",
"Principal": {
"Service": "sagemaker.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
• The AmazonSageMakerEdgeDeviceFleetPolicy IAM managed policy.
• The s3:PutObject action, as shown in the following IAM policy example.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"s3:PutObject"
],
"Resource": [
"*"
],
"Effect": "Allow"
}
]
}
• An Amazon S3 bucket created in the same AWS account and AWS Region as your Greengrass core
device. SageMaker Edge Manager requires an S3 bucket to create an edge device fleet, and to store
sample data from running inference on your device. For information about creating S3 buckets, see
Getting started with Amazon S3.
• A SageMaker edge device fleet that uses the same AWS IoT role alias as your Greengrass core device.
For more information, see Create an edge device fleet (p. 742).
• Your Greengrass core device registered as an edge device in your SageMaker Edge device fleet. The
edge device name must match the AWS IoT thing name for your core device. For more information, see
Register your Greengrass core device (p. 743).
Endpoints and ports
This component must be able to perform outbound requests to the following endpoints and ports, in
addition to endpoints and ports required for basic operation. For more information, see Allow device
traffic through a proxy or firewall (p. 807).
Endpoint Port Required Description
443
edge.sagemaker.region.amazonaws.com Yes Check device
registration
294
AWS IoT Greengrass Developer Guide, Version 2
SageMaker Edge Manager
Endpoint Port Required Description
status
and send
metrics to
SageMaker.
*.s3.amazonaws.com 443 Yes Upload
capture data
to the S3
bucket that
you specify.
You can
replace *
with the
name of
each bucket
where you
upload data.
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 299) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
>=1.0.3
The following table lists the dependencies for version 1.0.3 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Soft
Token exchange >=0.0.0 Hard
service (p. 407)
1.0.1 and 1.0.2
The following table lists the dependencies for versions 1.0.1 and 1.0.2 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Soft
Token exchange >=0.0.0 Hard
service (p. 407)
1.0.0
The following table lists the dependencies for version 1.0.0 of this component.
295
AWS IoT Greengrass Developer Guide, Version 2
SageMaker Edge Manager
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Soft
Token exchange >=0.0.0 Hard
service (p. 407)
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
Note
This section describes the configuration parameters that you set in the component. For more
information about the corresponding SageMaker Edge Manager configuration, see Edge
Manager Agent in the Amazon SageMaker Developer Guide.
DeviceFleetName
The name of the SageMaker Edge Manager device fleet that contains your Greengrass core device.
You must specify a value for this parameter in the configuration update when you deploy this
component.
BucketName
The name of the S3 bucket to which you upload captured inference data. The bucket name must
contain the string sagemaker.
If you set CaptureDataDestination to Cloud, or if you set CaptureDataPeriodicUpload to
true, then you must specify a value for this parameter in the configuration update when you deploy
this component.
Note
Capture data is an SageMaker feature that you use to upload inference input, inference
results, and additional inference data to an S3 bucket or a local directory for future analysis.
For more information about using capture data with SageMaker Edge Manager, see Manage
Model in the Amazon SageMaker Developer Guide.
CaptureDataBatchSize
(Optional) The size of a batch of capture data requests that the agent handles. This value must be
less than the buffer size that you specify in CaptureDataBufferSize. We recommend that you
don't exceed half the buffer size.
The agent handles a request batch when the number of requests in the buffer meets the
CaptureDataBatchSize number, or when the CaptureDataPushPeriodSeconds interval
elapses, whichever occurs first.
Default: 10
CaptureDataBufferSize
(Optional) The maximum number of capture data requests stored in the buffer.
Default: 30
CaptureDataDestination
(Optional) The destination where you store captured data. This parameter can have the following
values:
296
AWS IoT Greengrass Developer Guide, Version 2
SageMaker Edge Manager
• Cloud—Uploads captured data to the S3 bucket that you specify in BucketName.
• Disk—Writes captured data to the component's work directory.
If you specify Disk, you can also choose to periodically upload the captured data to your S3 bucket
by setting CaptureDataPeriodicUpload to true.
Default: Cloud
CaptureDataPeriodicUpload
(Optional) String value that specifies whether to periodically upload captured data. Supported
values are true and false.
Set this parameter to true if you set CaptureDataDestination to Disk, and you also want the
agent to periodically upload the captured data your S3 bucket.
Default: false
CaptureDataPeriodicUploadPeriodSeconds
(Optional) The interval in seconds at which SageMaker Edge Manager agent uploads captured data
to the S3 bucket. Use this parameter if you set CaptureDataPeriodicUpload to true.
Default: 8
CaptureDataPushPeriodSeconds
(Optional) The interval in seconds at which SageMaker Edge Manager agent handles a batch of
capture data requests from the buffer.
The agent handles a request batch when the number of requests in the buffer meets the
CaptureDataBatchSize number, or when the CaptureDataPushPeriodSeconds interval
elapses, whichever occurs first.
Default: 4
CaptureDataBase64EmbedLimit
(Optional) The maximum size in bytes of captured data that SageMaker Edge Manager agent
uploads.
Default: 3072
FolderPrefix
(Optional) The name of the folder to which the agent writes the captured data. If you set
CaptureDataDestination to Disk, the agent creates the folder in the directory that is specified
by CaptureDataDiskPath. If you set CaptureDataDestination to Cloud, or if you set
CaptureDataPeriodicUpload to true, the agent creates the folder in your S3 bucket.
Default: sme-capture
CaptureDataDiskPath
This feature is available in v1.1.0 and later versions of the SageMaker Edge Manager component.
(Optional) The path to the folder to which the agent creates the captured data folder. If you set
CaptureDataDestination to Disk, the agent creates the captured data folder in this directory.
If you don't specify this value, the agent creates the captured data folder in the component's work
directory. Use the FolderPrefix parameter to specify the name of the captured data folder.
Default: /greengrass/v2/work/aws.greengrass.SageMakerEdgeManager/capture
297
AWS IoT Greengrass Developer Guide, Version 2
SageMaker Edge Manager
SagemakerEdgeLogVerbose
(Optional) String value that specifies whether to enable debug logging. Supported values are true
and false.
Default: false
UnixSocketName
(Optional) The location of the SageMaker Edge Manager socket file descriptor on the core device.
Default: /tmp/aws.greengrass.SageMakerEdgeManager.sock
Example Example: Configuration merge update
The following example configuration specifies that the core device is part of the MyEdgeDeviceFleet
and that the agent writes capture data both to the device and to an S3 bucket. This configuration also
enables debug logging.
{
"DeviceFleetName": "MyEdgeDeviceFleet",
"BucketName": "DOC-EXAMPLE-BUCKET",
"CaptureDataDestination": "Disk",
"CaptureDataPeriodicUpload": "true",
"SagemakerEdgeLogVerbose": "true"
}
Local log file
This component uses the following log file.
Linux
/greengrass/v2/logs/aws.greengrass.SageMakerEdgeManager.log
Windows
C:\greengrass\v2\logs\aws.greengrass.SageMakerEdgeManager.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
Linux
sudo tail -f /greengrass/v2/logs/aws.greengrass.SageMakerEdgeManager.log
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\aws.greengrass.SageMakerEdgeManager.log -Tail 10
-Wait
298
AWS IoT Greengrass Developer Guide, Version 2
DLR image classification
Changelog
The following table describes the changes in each version of the component.
Version Changes
1.1.0 New features
• Adds support for Greengrass core devices running Amazon Linux 2.
• Adds the new CaptureDataDiskPath configuration parameter. You can
use this parameter to specify the path of the captured data folder on your
device.
1.0.3 Version updated for Greengrass nucleus version 2.4.0 release.
1.0.2 Bug fixes and improvements
Updates the installation script in the component lifecycle. Your core devices
must now have Python 3.6 or later, including pip for your version of Python,
installed on the device before you deploy this component.
1.0.1 Version updated for Greengrass nucleus version 2.3.0 release.
1.0.0 Initial version.
DLR image classification
The DLR image classification component (aws.greengrass.DLRImageClassification) contains
sample inference code to perform image classification inference using Deep Learning Runtime and
resnet-50 models. This component uses the variant DLR image classification model store (p. 313) and
the DLR installer (p. 319) components as dependencies to download DLR and the sample models.
To use this inference component with a custom-trained DLR model, create a custom version (p. 748) of
the dependent model store component. To use your own custom inference code, you can use the recipe
of this component as a template to create a custom inference component (p. 753).
Topics
• Versions (p. 299)
• Type (p. 300)
• Operating system (p. 300)
• Requirements (p. 300)
• Dependencies (p. 300)
• Configuration (p. 302)
• Local log file (p. 304)
• Changelog (p. 305)
Versions
This component has the following versions:
• 2.1.x
• 2.0.x
299
AWS IoT Greengrass Developer Guide, Version 2
DLR image classification
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
Requirements
This component has the following requirements:
• On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, GNU C Library (glibc) version
2.27 or later installed on the device.
• On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device.
Run the following command to install the dependencies.
sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-
dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
• On Raspberry Pi devices, OpenCV-Python installed on the device. Run the following command to
install OpenCV-Python.
pip3 install opencv-python
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 305) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.1.6
The following table lists the dependencies for version 2.1.6 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.6.0 Soft
DLR image classification model ~2.1.0 Hard
store (p. 313)
DLR (p. 319) ~1.6.0 Hard
300
AWS IoT Greengrass Developer Guide, Version 2
DLR image classification
2.1.4 - 2.1.5
The following table lists the dependencies for versions 2.1.4 to 2.1.5 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Soft
DLR image classification model ~2.1.0 Hard
store (p. 313)
DLR (p. 319) ~1.6.0 Hard
2.1.3
The following table lists the dependencies for version 2.1.3 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Soft
DLR image classification model ~2.1.0 Hard
store (p. 313)
DLR (p. 319) ~1.6.0 Hard
2.1.2
The following table lists the dependencies for version 2.1.2 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Soft
DLR image classification model ~2.1.0 Hard
store (p. 313)
DLR (p. 319) ~1.6.0 Hard
2.1.1
The following table lists the dependencies for version 2.1.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.2.0 Soft
DLR image classification model ~2.1.0 Hard
store (p. 313)
DLR (p. 319) ~1.6.0 Hard
2.0.x
The following table lists the dependencies for version 2.0.x of this component.
301
AWS IoT Greengrass Developer Guide, Version 2
DLR image classification
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) ~2.0.0 Soft
DLR image classification model ~2.0.0 Hard
store
DLR ~1.3.0 Soft
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
2.1.x
accessControl
(Optional) The object that contains the authorization policy (p. 552) that allows the
component to publish messages to the default notifications topic.
Default:
{
"aws.greengrass.ipc.mqttproxy": {
"aws.greengrass.DLRImageClassification:mqttproxy:1": {
"policyDescription": "Allows access to publish via topic ml/dlr/image-
classification.",
"operations": [
"aws.greengrass#PublishToIoTCore"
],
"resources": [
"ml/dlr/image-classification"
]
}
}
}
PublishResultsOnTopic
(Optional) The topic on which you want to publish the inference results. If you modify this value,
then you must also modify the value of resources in the accessControl parameter to match
your custom topic name.
Default: ml/dlr/image-classification
Accelerator
The accelerator that you want to use. Supported values are cpu and gpu.
The sample models in the dependent model component support only CPU acceleration. To use
GPU acceleration with a different custom model, create a custom model component (p. 748) to
override the public model component.
Default: cpu
ImageDirectory
(Optional) The path of the folder on the device where inference components read images. You
can modify this value to any location on your device to which you have read/write access.
302
AWS IoT Greengrass Developer Guide, Version 2
DLR image classification
Default: /greengrass/v2/packages/artifacts-unarchived/component-name/
image_classification/sample_images/
Note
If you set the value of UseCamera to true, then this configuration parameter is
ignored.
ImageName
(Optional) The name of the image that the inference component uses as an input to a make
prediction. The component looks for the image in the folder specified in ImageDirectory.
By default, the component uses the sample image in the default image directory. AWS IoT
Greengrass supports the following image formats: jpeg, jpg, png, and npy.
Default: cat.jpeg
Note
If you set the value of UseCamera to true, then this configuration parameter is
ignored.
InferenceInterval
(Optional) The time in seconds between each prediction made by the inference code. The
sample inference code runs indefinitely and repeats its predictions at the specified time interval.
For example, you can change this to a shorter interval if you want to use images taken by a
camera for real-time prediction.
Default: 3600
ModelResourceKey
(Optional) The models that are used in the dependent public model component. Modify this
parameter only if you override the public model component with a custom component.
Default:
{
"armv7l": "DLR-resnet50-armv7l-cpu-ImageClassification",
"aarch64": "DLR-resnet50-aarch64-cpu-ImageClassification",
"x86_64": "DLR-resnet50-x86_64-cpu-ImageClassification",
"windows": "DLR-resnet50-win-cpu-ImageClassification"
}
UseCamera
(Optional) String value that defines whether to use images from a camera connected to the
Greengrass core device. Supported values are true and false.
When you set this value to true, the sample inference code accesses the camera on your
device and runs inference locally on the captured image. The values of the ImageName and
ImageDirectory parameters are ignored. Make sure that the user running this component has
read/write access to the location where the camera stores captured images.
Default: false
Note
When you view the recipe of this component, the UseCamera configuration parameter
doesn't appear in the default configuration. However, you can modify the value of this
parameter in a configuration merge update (p. 500) when you deploy the component.
When you set UseCamera to true, you must also create a symlink to enable the
inference component to access your camera from the virtual environment that is
created by the runtime component. For more information about using a camera with
the sample inference components, see Update component configurations (p. 733).
303
AWS IoT Greengrass Developer Guide, Version 2
DLR image classification
2.0.x
MLRootPath
(Optional) The path of the folder on Linux core devices where inference components read
images and write inference results. You can modify this value to any location on your device to
which the user running this component has read/write access.
Default: /greengrass/v2/work/variant.DLR/greengrass_ml
Default: /greengrass/v2/work/variant.TensorFlowLite/greengrass_ml
Accelerator
The accelerator that you want to use. Supported values are cpu and gpu.
The sample models in the dependent model component support only CPU acceleration. To use
GPU acceleration with a different custom model, create a custom model component (p. 748) to
override the public model component.
Default: cpu
ImageName
(Optional) The name of the image that the inference component uses as an input to a make
prediction. The component looks for the image in the folder specified in ImageDirectory. The
default location is MLRootPath/images. AWS IoT Greengrass supports the following image
formats: jpeg, jpg, png, and npy.
Default: cat.jpeg
InferenceInterval
(Optional) The time in seconds between each prediction made by the inference code. The
sample inference code runs indefinitely and repeats its predictions at the specified time interval.
For example, you can change this to a shorter interval if you want to use images taken by a
camera for real-time prediction.
Default: 3600
ModelResourceKey
(Optional) The models that are used in the dependent public model component. Modify this
parameter only if you override the public model component with a custom component.
Default:
armv7l: "DLR-resnet50-armv7l-cpu-ImageClassification"
x86_64: "DLR-resnet50-x86_64-cpu-ImageClassification"
Local log file
This component uses the following log file.
Linux
/greengrass/v2/logs/aws.greengrass.DLRImageClassification.log
Windows
C:\greengrass\v2\logs\aws.greengrass.DLRImageClassification.log
304
AWS IoT Greengrass Developer Guide, Version 2
DLR image classification
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
Linux
sudo tail -f /greengrass/v2/logs/aws.greengrass.DLRImageClassification.log
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\aws.greengrass.DLRImageClassification.log -Tail
10 -Wait
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.1.6 Version updated for Greengrass nucleus version 2.5.0 release.
2.1.5 Component released in all AWS Regions.
2.1.4 Version updated for Greengrass nucleus version 2.4.0 release.
This version isn't available in Europe (London) (eu-west-2).
2.1.3 Version updated for Greengrass nucleus version 2.3.0 release.
2.1.2 Version updated for Greengrass nucleus version 2.2.0 release.
2.1.1 New features
• Use Deep Learning Runtime v1.6.0.
• Add support for sample image classification on Armv8 (AArch64)
platforms. This extends machine learning support for Greengrass core
devices running NVIDIA Jetson, such as the Jetson Nano.
• Enable camera integration for sample inference. Use the new UseCamera
configuration parameter to enable the sample inference code to access the
camera on your Greengrass core device and run inference locally on the
captured image.
• Add support for publishing inference results to the AWS Cloud. Use the
new PublishResultsOnTopic configuration parameter to specify the
topic on which you want to publish results.
• Add the new ImageDirectory configuration parameter that enables you
to specify a custom directory for the image on which you want to perform
inference.
Bug fixes and improvements
• Write inference results to the component log file instead of a separate
inference file.
• Use the AWS IoT Greengrass Core software logging module to log
component output.
305
AWS IoT Greengrass Developer Guide, Version 2
DLR object detection
Version Changes
• Use the AWS IoT Device SDK to read the component configuration and
apply configuration changes.
2.0.4 Initial version.
DLR object detection
The DLR object detection component (aws.greengrass.DLRObjectDetection) contains sample
inference code to perform object detection inference using Deep Learning Runtime and sample pre-
trained models. This component uses the variant DLR object detection model store (p. 316) and the
DLR installer (p. 319) components as dependencies to download DLR and the sample models.
To use this inference component with a custom-trained DLR model, create a custom version (p. 748) of
the dependent model store component. To use your own custom inference code, you can use the recipe
of this component as a template to create a custom inference component (p. 753).
Topics
• Versions (p. 306)
• Type (p. 306)
• Operating system (p. 306)
• Requirements (p. 307)
• Dependencies (p. 307)
• Configuration (p. 309)
• Local log file (p. 311)
• Changelog (p. 312)
Versions
This component has the following versions:
• 2.1.x
• 2.0.x
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
306
AWS IoT Greengrass Developer Guide, Version 2
DLR object detection
Requirements
This component has the following requirements:
• On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, GNU C Library (glibc) version
2.27 or later installed on the device.
• On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device.
Run the following command to install the dependencies.
sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-
dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
• On Raspberry Pi devices, OpenCV-Python installed on the device. Run the following command to
install OpenCV-Python.
pip3 install opencv-python
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 312) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.1.6
The following table lists the dependencies for version 2.1.6 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.6.0 Soft
DLR object detection model ~2.1.0 Hard
store (p. 316)
DLR (p. 319) ~1.6.0 Hard
2.1.4 - 2.1.5
The following table lists the dependencies for versions 2.1.4 to 2.1.5 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Soft
DLR object detection model ~2.1.0 Hard
store (p. 316)
DLR (p. 319) ~1.6.0 Hard
307
AWS IoT Greengrass Developer Guide, Version 2
DLR object detection
2.1.3
The following table lists the dependencies for version 2.1.3 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Soft
DLR object detection model ~2.1.0 Hard
store (p. 316)
DLR (p. 319) ~1.6.0 Hard
2.1.2
The following table lists the dependencies for version 2.1.2 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Soft
DLR object detection model ~2.1.0 Hard
store (p. 316)
DLR (p. 319) ~1.6.0 Hard
2.1.1
The following table lists the dependencies for version 2.1.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.2.0 Soft
DLR object detection model ~2.1.0 Hard
store (p. 316)
DLR (p. 319) ~1.6.0 Hard
2.0.x
The following table lists the dependencies for version 2.0.x of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) ~2.0.0 Soft
DLR object detection model ~2.0.0 Hard
store
DLR ~1.3.0 Soft
308
AWS IoT Greengrass Developer Guide, Version 2
DLR object detection
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
2.1.x
accessControl
(Optional) The object that contains the authorization policy (p. 552) that allows the
component to publish messages to the default notifications topic.
Default:
{
"aws.greengrass.ipc.mqttproxy": {
"aws.greengrass.DLRObjectDetection:mqttproxy:1": {
"policyDescription": "Allows access to publish via topic ml/dlr/object-
detection.",
"operations": [
"aws.greengrass#PublishToIoTCore"
],
"resources": [
"ml/dlr/object-detection"
]
}
}
}
PublishResultsOnTopic
(Optional) The topic on which you want to publish the inference results. If you modify this value,
then you must also modify the value of resources in the accessControl parameter to match
your custom topic name.
Default: ml/dlr/object-detection
Accelerator
The accelerator that you want to use. Supported values are cpu and gpu.
The sample models in the dependent model component support only CPU acceleration. To use
GPU acceleration with a different custom model, create a custom model component (p. 748) to
override the public model component.
Default: cpu
ImageDirectory
(Optional) The path of the folder on the device where inference components read images. You
can modify this value to any location on your device to which you have read/write access.
Default: /greengrass/v2/packages/artifacts-unarchived/component-name/
object_detection/sample_images/
Note
If you set the value of UseCamera to true, then this configuration parameter is
ignored.
ImageName
(Optional) The name of the image that the inference component uses as an input to a make
prediction. The component looks for the image in the folder specified in ImageDirectory.
309
AWS IoT Greengrass Developer Guide, Version 2
DLR object detection
By default, the component uses the sample image in the default image directory. AWS IoT
Greengrass supports the following image formats: jpeg, jpg, png, and npy.
Default: objects.jpg
Note
If you set the value of UseCamera to true, then this configuration parameter is
ignored.
InferenceInterval
(Optional) The time in seconds between each prediction made by the inference code. The
sample inference code runs indefinitely and repeats its predictions at the specified time interval.
For example, you can change this to a shorter interval if you want to use images taken by a
camera for real-time prediction.
Default: 3600
ModelResourceKey
(Optional) The models that are used in the dependent public model component. Modify this
parameter only if you override the public model component with a custom component.
Default:
{
"armv7l": "DLR-yolo3-armv7l-cpu-ObjectDetection",
"aarch64": "DLR-yolo3-aarch64-gpu-ObjectDetection",
"x86_64": "DLR-yolo3-x86_64-cpu-ObjectDetection",
"windows": "DLR-resnet50-win-cpu-ObjectDetection"
}
UseCamera
(Optional) String value that defines whether to use images from a camera connected to the
Greengrass core device. Supported values are true and false.
When you set this value to true, the sample inference code accesses the camera on your
device and runs inference locally on the captured image. The values of the ImageName and
ImageDirectory parameters are ignored. Make sure that the user running this component has
read/write access to the location where the camera stores captured images.
Default: false
Note
When you view the recipe of this component, the UseCamera configuration parameter
doesn't appear in the default configuration. However, you can modify the value of this
parameter in a configuration merge update (p. 500) when you deploy the component.
When you set UseCamera to true, you must also create a symlink to enable the
inference component to access your camera from the virtual environment that is
created by the runtime component. For more information about using a camera with
the sample inference components, see Update component configurations (p. 733).
2.0.x
MLRootPath
(Optional) The path of the folder on Linux core devices where inference components read
images and write inference results. You can modify this value to any location on your device to
which the user running this component has read/write access.
310
AWS IoT Greengrass Developer Guide, Version 2
DLR object detection
Default: /greengrass/v2/work/variant.DLR/greengrass_ml
Default: /greengrass/v2/work/variant.TensorFlowLite/greengrass_ml
Accelerator
Do not modify. Currently, the only supported value for the accelerator is cpu, because the
models in the dependent model components are compiled only for the CPU accelerator.
ImageName
(Optional) The name of the image that the inference component uses as an input to a make
prediction. The component looks for the image in the folder specified in ImageDirectory. The
default location is MLRootPath/images. AWS IoT Greengrass supports the following image
formats: jpeg, jpg, png, and npy.
Default: objects.jpg
InferenceInterval
(Optional) The time in seconds between each prediction made by the inference code. The
sample inference code runs indefinitely and repeats its predictions at the specified time interval.
For example, you can change this to a shorter interval if you want to use images taken by a
camera for real-time prediction.
Default: 3600
ModelResourceKey
(Optional) The models that are used in the dependent public model component. Modify this
parameter only if you override the public model component with a custom component.
Default:
{
armv7l: "DLR-yolo3-armv7l-cpu-ObjectDetection",
x86_64: "DLR-yolo3-x86_64-cpu-ObjectDetection"
}
Local log file
This component uses the following log file.
Linux
/greengrass/v2/logs/aws.greengrass.DLRObjectDetection.log
Windows
C:\greengrass\v2\logs\aws.greengrass.DLRObjectDetection.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
311
AWS IoT Greengrass Developer Guide, Version 2
DLR object detection
Linux
sudo tail -f /greengrass/v2/logs/aws.greengrass.DLRObjectDetection.log
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\aws.greengrass.DLRObjectDetection.log -Tail 10 -
Wait
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.1.6 Version updated for Greengrass nucleus version 2.5.0 release.
2.1.5 Component released in all AWS Regions.
2.1.4 Version updated for Greengrass nucleus version 2.4.0 release.
This version isn't available in Europe (London) (eu-west-2).
2.1.3 Version updated for Greengrass nucleus version 2.3.0 release.
2.1.2 Bug fixes and improvements
• Fixes an image scaling issue that resulted in inaccurate bounding boxes in
the sample DLR object detection inference results.
2.1.1 New features
• Use Deep Learning Runtime v1.6.0.
• Add support for sample object detection on Armv8 (AArch64) platforms.
This extends machine learning support for Greengrass core devices running
NVIDIA Jetson, such as the Jetson Nano.
• Enable camera integration for sample inference. Use the new UseCamera
configuration parameter to enable the sample inference code to access the
camera on your Greengrass core device and run inference locally on the
captured image.
• Add support for publishing inference results to the AWS Cloud. Use the
new PublishResultsOnTopic configuration parameter to specify the
topic on which you want to publish results.
• Add the new ImageDirectory configuration parameter that enables you
to specify a custom directory for the image on which you want to perform
inference.
Bug fixes and improvements
• Write inference results to the component log file instead of a separate
inference file.
• Use the AWS IoT Greengrass Core software logging module to log
component output.
• Use the AWS IoT Device SDK to read the component configuration and
apply configuration changes.
312
AWS IoT Greengrass Developer Guide, Version 2
DLR image classification model store
Version Changes
2.0.4 Initial version.
DLR image classification model store
The DLR image classification model store is a machine learning model component that contains pre-
trained ResNet-50 models as Greengrass artifacts. The pre-trained models used in this component are
fetched from the GluonCV Model Zoo and are compiled using SageMaker Neo Deep Learning Runtime.
The DLR image classification (p. 299) inference component uses this component as a dependency for
the model source. To use a custom-trained DLR model, create a custom version (p. 748) of this model
component, and include your custom model as a component artifact. You can use the recipe of this
component as a template to create custom model components.
Note
The name of the DLR image classification model store component varies depending
on its version. The component name for version 2.1.x and later versions is
variant.DLR.ImageClassification.ModelStore. The component name for version 2.0.x
is variant.ImageClassification.ModelStore.
Topics
• Versions (p. 313)
• Type (p. 313)
• Operating system (p. 313)
• Requirements (p. 314)
• Dependencies (p. 314)
• Configuration (p. 315)
• Local log file (p. 315)
• Changelog (p. 315)
Versions
This component has the following versions:
• 2.1.x (variant.DLR.ImageClassification.ModelStore)
• 2.0.x (variant.ImageClassification.ModelStore)
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
313
AWS IoT Greengrass Developer Guide, Version 2
DLR image classification model store
• Windows
Requirements
This component has the following requirements:
• On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, GNU C Library (glibc) version
2.27 or later installed on the device.
• On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device.
Run the following command to install the dependencies.
sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-
dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
• On Raspberry Pi devices, OpenCV-Python installed on the device. Run the following command to
install OpenCV-Python.
pip3 install opencv-python
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 315) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.1.5
The following table lists the dependencies for version 2.1.5 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.6.0 Soft
2.1.4
The following table lists the dependencies for version 2.1.4 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Soft
2.1.3
The following table lists the dependencies for version 2.1.3 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Soft
314
AWS IoT Greengrass Developer Guide, Version 2
DLR image classification model store
2.1.2
The following table lists the dependencies for version 2.1.2 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Soft
2.1.1
The following table lists the dependencies for version 2.1.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.2.0 Soft
2.0.x
The following table lists the dependencies for version 2.0.x of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) ~2.0.0 Soft
Configuration
This component doesn't have any configuration parameters.
Local log file
This component doesn't output logs.
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.1.5 New features
• Adds sample image classification models for Windows core devices.
• Version updated for Greengrass nucleus version 2.5.0 release.
2.1.4 Version updated for Greengrass nucleus version 2.4.0 release.
2.1.3 Version updated for Greengrass nucleus version 2.3.0 release.
2.1.2 Version updated for Greengrass nucleus version 2.2.0 release.
2.1.1 New features
• Add a sample ResNet-50 image classification model for Armv8 (AArch64)
platforms. This extends machine learning support for Greengrass core
devices running NVIDIA Jetson, such as the Jetson Nano.
315
AWS IoT Greengrass Developer Guide, Version 2
DLR object detection model store
Version Changes
2.0.4 Initial version.
DLR object detection model store
The DLR object detection model store is a machine learning model component that contains pre-trained
YOLOv3 models as Greengrass artifacts. The sample models used in this component are fetched from the
GluonCV Model Zoo and compiled using SageMaker Neo Deep Learning Runtime.
The DLR object detection (p. 306) inference component uses this component as a dependency for
the model source. To use a custom-trained DLR model, create a custom version (p. 748) of this model
component, and include your custom model as a component artifact. You can use the recipe of this
component as a template to create custom model components.
Note
The name of the DLR object detection model store component varies depending
on its version. The component name for version 2.1.x and later versions is
variant.DLR.ObjectDetection.ModelStore. The component name for version 2.0.x is
variant.ObjectDetection.ModelStore.
Topics
• Versions (p. 316)
• Type (p. 316)
• Operating system (p. 316)
• Requirements (p. 317)
• Dependencies (p. 317)
• Configuration (p. 318)
• Local log file (p. 318)
• Changelog (p. 318)
Versions
This component has the following versions:
• 2.1.x
• 2.0.x
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
316
AWS IoT Greengrass Developer Guide, Version 2
DLR object detection model store
Requirements
This component has the following requirements:
• On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, GNU C Library (glibc) version
2.27 or later installed on the device.
• On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device.
Run the following command to install the dependencies.
sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-
dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
• On Raspberry Pi devices, OpenCV-Python installed on the device. Run the following command to
install OpenCV-Python.
pip3 install opencv-python
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 318) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.1.5 and 2.1.6
The following table lists the dependencies for versions 2.1.5 and 2.1.6 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.6.0 Soft
2.1.4
The following table lists the dependencies for version 2.1.4 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Soft
2.1.3
The following table lists the dependencies for version 2.1.3 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Soft
2.1.2
The following table lists the dependencies for version 2.1.2 of this component.
317
AWS IoT Greengrass Developer Guide, Version 2
DLR object detection model store
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Soft
2.1.1
The following table lists the dependencies for version 2.1.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.2.0 Soft
2.0.x
The following table lists the dependencies for version 2.0.x of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) ~2.0.0 Soft
Configuration
This component doesn't have any configuration parameters.
Local log file
This component doesn't output logs.
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.1.6 Adds a CPU model to fix an issue on Armv8 (AArch64) devices.
2.1.5 New features
• Adds sample object detection models for Windows core devices.
• Version updated for Greengrass nucleus version 2.5.0 release.
2.1.4 Version updated for Greengrass nucleus version 2.4.0 release.
2.1.3 Version updated for Greengrass nucleus version 2.3.0 release.
2.1.2 Version updated for Greengrass nucleus version 2.2.0 release.
2.1.1 New features
• Add a sample YOLOv3 object detection model for Armv8 (AArch64)
platforms. This extends machine learning support for Greengrass core
devices running NVIDIA Jetson, such as the Jetson Nano.
2.0.4 Initial version.
318
AWS IoT Greengrass Developer Guide, Version 2
DLR installer
DLR installer
The DLR installer component (variant.DLR) contains a script that installs Deep Learning Runtime (DLR)
and its dependencies in a virtual environment on your device. The DLR image classification (p. 299)
and DLR object detection (p. 306) components use this component as a dependency for installing DLR.
Component version 1.6.x installs DLR v1.6.0 and component version 1.3.x installs DLR v1.3.0.
To use a different runtime, you can use the recipe of this component as a template to create a custom
runtime component (p. 746).
Topics
• Versions (p. 319)
• Type (p. 319)
• Operating system (p. 319)
• Requirements (p. 319)
• Dependencies (p. 320)
• Configuration (p. 321)
• Usage (p. 322)
• Local log file (p. 323)
• Changelog (p. 323)
Versions
This component has the following versions:
• 1.6.x
• 1.3.x
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
Requirements
This component has the following requirements:
• On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, GNU C Library (glibc) version
2.27 or later installed on the device.
• On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device.
Run the following command to install the dependencies.
319
AWS IoT Greengrass Developer Guide, Version 2
DLR installer
sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-
dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
• On Raspberry Pi devices, OpenCV-Python installed on the device. Run the following command to
install OpenCV-Python.
pip3 install opencv-python
Endpoints and ports
By default, this component uses an installer script to install packages using the apt, yum, brew, and
pip commands, depending on what platform the core device uses. This component must be able to
perform outbound requests to various package indexes and repositories to run the installer script. To
allow this component's outbound traffic through a proxy or firewall, you must identify the endpoints for
the package indexes and repositories where your core device connects to install.
Consider the following when you identify endpoints required for this component's install script:
• The endpoints depend on the core device's platform. For example, a core device that runs Ubuntu
uses apt rather than yum or brew. Additionally, devices that use the same package index might have
different source lists, so they might retrieve packages from different repositories.
• The endpoints might differ between multiple devices that use the same package index, because each
device has its own source lists that define where to retrieve packages.
• The endpoints might change over time. Each package index provides the URLs of the repositories
where you download packages, and the owner of a package can change what URLs the package index
provides.
For more information about the dependencies that this component installs, and how to disable the
installer script, see the UseInstaller (p. 322) configuration parameter.
For more information about endpoints and ports required for basic operation, see Allow device traffic
through a proxy or firewall (p. 807).
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 323) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
1.6.6
The following table lists the dependencies for version 1.6.6 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.6.0 Soft
1.6.5 and 1.6.4
The following table lists the dependencies for versions 1.6.5 and 1.6.4 of this component.
320
AWS IoT Greengrass Developer Guide, Version 2
DLR installer
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Soft
1.6.3
The following table lists the dependencies for version 1.6.3 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Soft
1.6.2
The following table lists the dependencies for version 1.6.2 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Soft
1.6.1
The following table lists the dependencies for version 1.6.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.2.0 Soft
1.3.x
The following table lists the dependencies for version 1.3.x of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) ~2.0.0 Soft
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
MLRootPath
(Optional) The path of the folder on Linux core devices where inference components read images
and write inference results. You can modify this value to any location on your device to which the
user running this component has read/write access.
Default: /greengrass/v2/work/variant.DLR/greengrass_ml
321
AWS IoT Greengrass Developer Guide, Version 2
DLR installer
WindowsMLRootPath
This feature is available in v1.6.6 and later of this component.
(Optional) The path of the folder on Windows core device where inference components read images
and write inference results. You can modify this value to any location on your device to which the
user running this component has read/write access.
Default: C:\greengrass\v2\work\variant.DLR\greengrass_ml
UseInstaller
(Optional) String value that defines whether to use the installer script in this component to install
DLR and its dependencies. Supported values are true and false.
Set this value to false if you want to use a custom script for DLR installation, or if you want to
include runtime dependencies in a pre-built Linux image. To use this component with the AWS-
provided DLR inference components, you will need to install the following libraries, including any
dependencies, and make them available the to default Greengrass system user.
• Python 3.7 or later, including pip for your version of Python.
• Deep Learning Runtime v1.6.0
• NumPy.
• OpenCV-Python.
• AWS IoT Device SDK v2 for Python.
• AWS Common Runtime (CRT) Python.
• Picamera, for Raspberry Pi devices only.
• awscam module, for AWS DeepLens devices only.
Default: true
Usage
Use this component with the UseInstaller configuration parameter set to true to install DLR and its
dependencies on your device. The component sets up a virtual environment on your device that includes
the OpenCV and NumPy libraries that are required for DLR.
Note
The installer script in this component also installs the latest versions of additional system
libraries that are required to configure the virtual environment on your device and to use the
installed machine learning framework. This might upgrade the existing system libraries on
your device. Review the following table for the list of libraries that this component installs for
each supported operating system. If you want to customize this installation process, set the
UseInstaller configuration parameter to false, and develop your own installer script.
Platform Libraries installed on the Libraries installed in the virtual
device system environment
Armv7l build-essential, cmake, ca- setuptools, wheel
certificates, git
Amazon Linux 2 mesa-libGL None
Ubuntu wget None
When you deploy your inference component, this runtime component first verifies if your device already
has DLR and its dependencies installed, and if not, then it installs them for you.
322
AWS IoT Greengrass Developer Guide, Version 2
DLR installer
Local log file
This component uses the following log file.
Linux
/greengrass/v2/logs/variant.DLR.log
Windows
C:\greengrass\v2\logs\variant.DLR.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
Linux
sudo tail -f /greengrass/v2/logs/variant.DLR.log
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\variant.DLR.log -Tail 10 -Wait
Changelog
The following table describes the changes in each version of the component.
Version Changes
1.6.6 New feature
• Adds support for core devices that run Windows.
• Adds the new WindowsMLRootPath configuration parameter that you can
use to configure the inference results folder on Windows core devices.
1.6.5 New feature
• Adds the new UseInstaller configuration parameter that you can use to
disable the installation script in this component.
1.6.4 Version updated for Greengrass nucleus version 2.4.0 release.
1.6.3 Version updated for Greengrass nucleus version 2.3.0 release.
1.6.2 Version updated for Greengrass nucleus version 2.2.0 release.
1.6.1 New features
• Install Deep Learning Runtime v1.6.0 and its dependencies.
• Add support for installing DLR on Armv8 (AArch64) platforms. This extends
machine learning support for Greengrass core devices running NVIDIA
Jetson, such as the Jetson Nano.
323
AWS IoT Greengrass Developer Guide, Version 2
TensorFlow Lite image classification
Version Changes
Bug fixes and improvements
• Install the AWS IoT Device SDK in the virtual environment to read the
component configuration and apply configuration changes.
• Additional minor bug fixes and improvements.
1.3.2 Initial version. Installs DLR v1.3.0.
TensorFlow Lite image classification
The TensorFlow Lite image classification component
(aws.greengrass.TensorFlowLiteImageClassification) contains sample inference code to
perform image classification inference using the TensorFlow Lite runtime and a sample pre-trained
MobileNet 1.0 quantized model. This component uses the variant TensorFlow Lite image classification
model store (p. 334) and the TensorFlow Lite installer (p. 339) components as dependencies to
download the TensorFlow Lite runtime and the sample model.
To use this inference component with a custom-trained TensorFlow Lite model, create a custom
version (p. 748) of the dependent model store component. To use your own custom inference code, you
can use the recipe of this component as a template to create a custom inference component (p. 753).
Topics
• Versions (p. 324)
• Type (p. 324)
• Operating system (p. 324)
• Requirements (p. 325)
• Dependencies (p. 325)
• Configuration (p. 326)
• Local log file (p. 328)
• Changelog (p. 329)
Versions
This component has the following versions:
• 2.1.x
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
324
AWS IoT Greengrass Developer Guide, Version 2
TensorFlow Lite image classification
Requirements
This component has the following requirements:
• On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, GNU C Library (glibc) version
2.27 or later installed on the device.
• On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device.
Run the following command to install the dependencies.
sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-
dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
• On Raspberry Pi devices, OpenCV-Python installed on the device. Run the following command to
install OpenCV-Python.
pip3 install opencv-python
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 329) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.1.4
The following table lists the dependencies for version 2.1.4 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.6.0 Soft
TensorFlow Lite image >=2.1.0 <2.2.0 Hard
classification model
store (p. 334)
TensorFlow Lite (p. 339) >=2.5.0 <2.6.0 Hard
2.1.3
The following table lists the dependencies for version 2.1.3 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Soft
TensorFlow Lite image >=2.1.0 <2.2.0 Hard
classification model
store (p. 334)
TensorFlow Lite (p. 339) >=2.5.0 <2.6.0 Hard
325
AWS IoT Greengrass Developer Guide, Version 2
TensorFlow Lite image classification
2.1.2
The following table lists the dependencies for version 2.1.2 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Soft
TensorFlow Lite image >=2.1.0 <2.2.0 Hard
classification model
store (p. 334)
TensorFlow Lite (p. 339) >=2.5.0 <2.6.0 Hard
2.1.1
The following table lists the dependencies for version 2.1.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Soft
TensorFlow Lite image >=2.1.0 <2.2.0 Hard
classification model
store (p. 334)
TensorFlow Lite (p. 339) >=2.5.0 <2.6.0 Hard
2.1.0
The following table lists the dependencies for version 2.1.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.2.0 Soft
TensorFlow Lite image >=2.1.0 <2.2.0 Hard
classification model
store (p. 334)
TensorFlow Lite (p. 339) >=2.5.0 <2.6.0 Hard
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
accessControl
(Optional) The object that contains the authorization policy (p. 552) that allows the component to
publish messages to the default notifications topic.
Default:
326
AWS IoT Greengrass Developer Guide, Version 2
TensorFlow Lite image classification
"aws.greengrass.ipc.mqttproxy": {
"aws.greengrass.TensorFlowLiteImageClassification:mqttproxy:1": {
"policyDescription": "Allows access to publish via topic ml/tflite/image-
classification.",
"operations": [
"aws.greengrass#PublishToIoTCore"
],
"resources": [
"ml/tflite/image-classification"
]
}
}
}
PublishResultsOnTopic
(Optional) The topic on which you want to publish the inference results. If you modify this value,
then you must also modify the value of resources in the accessControl parameter to match
your custom topic name.
Default: ml/tflite/image-classification
Accelerator
The accelerator that you want to use. Supported values are cpu and gpu.
The sample models in the dependent model component support only CPU acceleration. To use GPU
acceleration with a different custom model, create a custom model component (p. 748) to override
the public model component.
Default: cpu
ImageDirectory
(Optional) The path of the folder on the device where inference components read images. You can
modify this value to any location on your device to which you have read/write access.
Default: /greengrass/v2/packages/artifacts-unarchived/component-name/
image_classification/sample_images/
Note
If you set the value of UseCamera to true, then this configuration parameter is ignored.
ImageName
(Optional) The name of the image that the inference component uses as an input to a make
prediction. The component looks for the image in the folder specified in ImageDirectory. By
default, the component uses the sample image in the default image directory. AWS IoT Greengrass
supports the following image formats: jpeg, jpg, png, and npy.
Default: cat.jpeg
Note
If you set the value of UseCamera to true, then this configuration parameter is ignored.
InferenceInterval
(Optional) The time in seconds between each prediction made by the inference code. The sample
inference code runs indefinitely and repeats its predictions at the specified time interval. For
example, you can change this to a shorter interval if you want to use images taken by a camera for
real-time prediction.
Default: 3600
327
AWS IoT Greengrass Developer Guide, Version 2
TensorFlow Lite image classification
ModelResourceKey
(Optional) The models that are used in the dependent public model component. Modify this
parameter only if you override the public model component with a custom component.
Default:
{
"model": "TensorFlowLite-Mobilenet"
}
UseCamera
(Optional) String value that defines whether to use images from a camera connected to the
Greengrass core device. Supported values are true and false.
When you set this value to true, the sample inference code accesses the camera on your device and
runs inference locally on the captured image. The values of the ImageName and ImageDirectory
parameters are ignored. Make sure that the user running this component has read/write access to
the location where the camera stores captured images.
Default: false
Note
When you view the recipe of this component, the UseCamera configuration parameter
doesn't appear in the default configuration. However, you can modify the value of this
parameter in a configuration merge update (p. 500) when you deploy the component.
When you set UseCamera to true, you must also create a symlink to enable the inference
component to access your camera from the virtual environment that is created by the
runtime component. For more information about using a camera with the sample inference
components, see Update component configurations (p. 733).
Local log file
This component uses the following log file.
Linux
/greengrass/v2/logs/aws.greengrass.TensorFlowLiteImageClassification.log
Windows
C:\greengrass\v2\logs\aws.greengrass.TensorFlowLiteImageClassification.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
Linux
sudo tail -f /greengrass/v2/logs/
aws.greengrass.TensorFlowLiteImageClassification.log
328
AWS IoT Greengrass Developer Guide, Version 2
TensorFlow Lite object detection
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs
\aws.greengrass.TensorFlowLiteImageClassification.log -Tail 10 -Wait
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.1.4 Version updated for Greengrass nucleus version 2.5.0 release.
2.1.3 Version updated for Greengrass nucleus version 2.4.0 release.
2.1.2 Version updated for Greengrass nucleus version 2.3.0 release.
2.1.1 Version updated for Greengrass nucleus version 2.2.0 release.
2.1.0 Initial version.
TensorFlow Lite object detection
The TensorFlow Lite object detection component
(aws.greengrass.TensorFlowLiteObjectDetection) contains sample inference code to perform
object detection inference using TensorFlow Lite and a sample pre-trained Single Shot Detection
(SSD) MobileNet 1.0 model. This component uses the variant TensorFlow Lite object detection model
store (p. 337) and the TensorFlow Lite installer (p. 339) components as dependencies to download
TensorFlow Lite and the sample model.
To use this inference component with a custom-trained TensorFlow Lite model, you can create a custom
version (p. 748) of the dependent model store component. To use your own custom inference code, use
the recipe of this component as a template to create a custom inference component (p. 753).
Topics
• Versions (p. 329)
• Type (p. 330)
• Operating system (p. 330)
• Requirements (p. 330)
• Dependencies (p. 330)
• Configuration (p. 332)
• Local log file (p. 333)
• Changelog (p. 334)
Versions
This component has the following versions:
• 2.1.x
329
AWS IoT Greengrass Developer Guide, Version 2
TensorFlow Lite object detection
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
Requirements
This component has the following requirements:
• On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, GNU C Library (glibc) version
2.27 or later installed on the device.
• On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device.
Run the following command to install the dependencies.
sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-
dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
• On Raspberry Pi devices, OpenCV-Python installed on the device. Run the following command to
install OpenCV-Python.
pip3 install opencv-python
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 334) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.1.4
The following table lists the dependencies for version 2.1.4 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.6.0 Soft
TensorFlow Lite image >=2.1.0 <2.2.0 Hard
classification model
store (p. 334)
TensorFlow Lite (p. 339) >=2.5.0 <2.6.0 Hard
330
AWS IoT Greengrass Developer Guide, Version 2
TensorFlow Lite object detection
2.1.3
The following table lists the dependencies for version 2.1.3 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Soft
TensorFlow Lite image >=2.1.0 <2.2.0 Hard
classification model
store (p. 334)
TensorFlow Lite (p. 339) >=2.5.0 <2.6.0 Hard
2.1.2
The following table lists the dependencies for version 2.1.2 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Soft
TensorFlow Lite image >=2.1.0 <2.2.0 Hard
classification model
store (p. 334)
TensorFlow Lite (p. 339) >=2.5.0 <2.6.0 Hard
2.1.1
The following table lists the dependencies for version 2.1.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Soft
TensorFlow Lite image >=2.1.0 <2.2.0 Hard
classification model
store (p. 334)
TensorFlow Lite (p. 339) >=2.5.0 <2.6.0 Hard
2.1.0
The following table lists the dependencies for version 2.1.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.2.0 Soft
TensorFlow Lite image >=2.1.0 <2.2.0 Hard
classification model
store (p. 334)
TensorFlow Lite (p. 339) >=2.5.0 <2.6.0 Hard
331
AWS IoT Greengrass Developer Guide, Version 2
TensorFlow Lite object detection
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
accessControl
(Optional) The object that contains the authorization policy (p. 552) that allows the component to
publish messages to the default notifications topic.
Default:
{
"aws.greengrass.ipc.mqttproxy": {
"aws.greengrass.TensorFlowLiteObjectDetection:mqttproxy:1": {
"policyDescription": "Allows access to publish via topic ml/tflite/object-
detection.",
"operations": [
"aws.greengrass#PublishToIoTCore"
],
"resources": [
"ml/tflite/object-detection"
]
}
}
}
PublishResultsOnTopic
(Optional) The topic on which you want to publish the inference results. If you modify this value,
then you must also modify the value of resources in the accessControl parameter to match
your custom topic name.
Default: ml/tflite/object-detection
Accelerator
The accelerator that you want to use. Supported values are cpu and gpu.
The sample models in the dependent model component support only CPU acceleration. To use GPU
acceleration with a different custom model, create a custom model component (p. 748) to override
the public model component.
Default: cpu
ImageDirectory
(Optional) The path of the folder on the device where inference components read images. You can
modify this value to any location on your device to which you have read/write access.
Default: /greengrass/v2/packages/artifacts-unarchived/component-name/
object_detection/sample_images/
Note
If you set the value of UseCamera to true, then this configuration parameter is ignored.
ImageName
(Optional) The name of the image that the inference component uses as an input to a make
prediction. The component looks for the image in the folder specified in ImageDirectory. By
default, the component uses the sample image in the default image directory. AWS IoT Greengrass
supports the following image formats: jpeg, jpg, png, and npy.
Default: objects.jpg
332
AWS IoT Greengrass Developer Guide, Version 2
TensorFlow Lite object detection
Note
If you set the value of UseCamera to true, then this configuration parameter is ignored.
InferenceInterval
(Optional) The time in seconds between each prediction made by the inference code. The sample
inference code runs indefinitely and repeats its predictions at the specified time interval. For
example, you can change this to a shorter interval if you want to use images taken by a camera for
real-time prediction.
Default: 3600
ModelResourceKey
(Optional) The models that are used in the dependent public model component. Modify this
parameter only if you override the public model component with a custom component.
Default:
{
"model": "TensorFlowLite-SSD"
}
UseCamera
(Optional) String value that defines whether to use images from a camera connected to the
Greengrass core device. Supported values are true and false.
When you set this value to true, the sample inference code accesses the camera on your device and
runs inference locally on the captured image. The values of the ImageName and ImageDirectory
parameters are ignored. Make sure that the user running this component has read/write access to
the location where the camera stores captured images.
Default: false
Note
When you view the recipe of this component, the UseCamera configuration parameter
doesn't appear in the default configuration. However, you can modify the value of this
parameter in a configuration merge update (p. 500) when you deploy the component.
When you set UseCamera to true, you must also create a symlink to enable the inference
component to access your camera from the virtual environment that is created by the
runtime component. For more information about using a camera with the sample inference
components, see Update component configurations (p. 733).
Note
When you view the recipe of this component, the UseCamera configuration parameter doesn't
appear in the default configuration. However, you can modify the value of this parameter in a
configuration merge update (p. 500) when you deploy the component.
When you set UseCamera to true, you must also create a symlink to enable the inference
component to access your camera from the virtual environment that is created by the runtime
component. For more information about using a camera with the sample inference components,
see Update component configurations (p. 733).
Local log file
This component uses the following log file.
Linux
/greengrass/v2/logs/aws.greengrass.TensorFlowLiteObjectDetection.log
333
AWS IoT Greengrass Developer Guide, Version 2
TensorFlow Lite image classification model store
Windows
C:\greengrass\v2\logs\aws.greengrass.TensorFlowLiteObjectDetection.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
Linux
sudo tail -f /greengrass/v2/logs/aws.greengrass.TensorFlowLiteObjectDetection.log
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\aws.greengrass.TensorFlowLiteObjectDetection.log
-Tail 10 -Wait
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.1.5 Version updated for Greengrass nucleus version 2.5.0 release.
2.1.4 Version updated for Greengrass nucleus version 2.4.0 release.
2.1.3 Version updated for Greengrass nucleus version 2.3.0 release.
2.1.2 Version updated for Greengrass nucleus version 2.2.0 release.
2.1.1 Bug fixes and improvements
• Fixes an image scaling issue that resulted in inaccurate bounding boxes in
the sample TensorFlow Lite object detection inference results.
2.1.0 Initial version.
TensorFlow Lite image classification model store
The TensorFlow Lite image classification model store
(variant.TensorFlowLite.ImageClassification.ModelStore) is a machine learning model
component that contains a pre-trained MobileNet v1 model as a Greengrass artifact. The sample model
used in this component is fetched from the TensorFlow Hub and implemented using TensorFlow Lite.
The TensorFlow Lite image classification (p. 324) inference component uses this component as a
dependency for the model source. To use a custom-trained TensorFlow Lite model, create a custom
version (p. 748) of this model component, and include your custom model as a component artifact. You
can use the recipe of this component as a template to create custom model components.
Topics
• Versions (p. 335)
334
AWS IoT Greengrass Developer Guide, Version 2
TensorFlow Lite image classification model store
• Type (p. 335)
• Operating system (p. 335)
• Requirements (p. 335)
• Dependencies (p. 335)
• Configuration (p. 336)
• Local log file (p. 336)
• Changelog (p. 337)
Versions
This component has the following versions:
• 2.1.x
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
Requirements
This component has the following requirements:
• On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, GNU C Library (glibc) version
2.27 or later installed on the device.
• On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device.
Run the following command to install the dependencies.
sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-
dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
• On Raspberry Pi devices, OpenCV-Python installed on the device. Run the following command to
install OpenCV-Python.
pip3 install opencv-python
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 337) of this component and the semantic version constraints that define the component
335
AWS IoT Greengrass Developer Guide, Version 2
TensorFlow Lite image classification model store
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.1.4
The following table lists the dependencies for version 2.1.4 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.6.0 Soft
2.1.3
The following table lists the dependencies for version 2.1.3 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Soft
2.1.2
The following table lists the dependencies for version 2.1.2 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Soft
2.1.1
The following table lists the dependencies for version 2.1.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Soft
2.1.0
The following table lists the dependencies for version 2.1.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.2.0 Soft
Configuration
This component doesn't have any configuration parameters.
Local log file
This component doesn't output logs.
336
AWS IoT Greengrass Developer Guide, Version 2
TensorFlow Lite object detection model store
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.1.4 Version updated for Greengrass nucleus version 2.5.0 release.
2.1.3 Version updated for Greengrass nucleus version 2.4.0 release.
2.1.2 Version updated for Greengrass nucleus version 2.3.0 release.
2.1.1 Version updated for Greengrass nucleus version 2.2.0 release.
2.1.0 Initial version.
TensorFlow Lite object detection model store
The TensorFlow Lite object detection model store
(variant.TensorFlowLite.ObjectDetection.ModelStore) is a machine learning model
component that contains a pre-trained Single Shot Detection (SSD) MobileNet model as a Greengrass
artifact. The sample model used in this component is fetched from the TensorFlow Hub and
implemented using TensorFlow Lite.
The TensorFlow Lite object detection (p. 329) inference component uses this component as a
dependency for the model source. To use a custom-trained TensorFlow Lite model, create a custom
version (p. 748) of this model component, and include your custom model as a component artifact. You
can use the recipe of this component as a template to create custom model components.
Topics
• Versions (p. 337)
• Type (p. 337)
• Operating system (p. 338)
• Requirements (p. 338)
• Dependencies (p. 338)
• Configuration (p. 339)
• Local log file (p. 339)
• Changelog (p. 339)
Versions
This component has the following versions:
• 2.1.x
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
337
AWS IoT Greengrass Developer Guide, Version 2
TensorFlow Lite object detection model store
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
Requirements
This component has the following requirements:
• On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, GNU C Library (glibc) version
2.27 or later installed on the device.
• On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device.
Run the following command to install the dependencies.
sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-
dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
• On Raspberry Pi devices, OpenCV-Python installed on the device. Run the following command to
install OpenCV-Python.
pip3 install opencv-python
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 339) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.1.4
The following table lists the dependencies for version 2.1.4 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.6.0 Soft
2.1.3
The following table lists the dependencies for version 2.1.3 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Soft
2.1.2
The following table lists the dependencies for version 2.1.2 of this component.
338
AWS IoT Greengrass Developer Guide, Version 2
TensorFlow Lite installer
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Soft
2.1.1
The following table lists the dependencies for version 2.1.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Soft
2.1.0
The following table lists the dependencies for version 2.1.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.2.0 Soft
Configuration
This component doesn't have any configuration parameters.
Local log file
This component doesn't output logs.
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.1.4 Version updated for Greengrass nucleus version 2.5.0 release.
2.1.3 Version updated for Greengrass nucleus version 2.4.0 release.
2.1.2 Version updated for Greengrass nucleus version 2.3.0 release.
2.1.1 Version updated for Greengrass nucleus version 2.2.0 release.
2.1.0 Initial version.
TensorFlow Lite installer
The TensorFlow Lite installer component (variant.TensorFlowLite) contains a script that
installs TensorFlow Lite version 2.5.0 and its dependencies in a virtual environment on your device.
The TensorFlow Lite image classification (p. 324) and TensorFlow Lite object detection (p. 329)
component use this runtime component as a dependency for installing TensorFlow Lite.
339
AWS IoT Greengrass Developer Guide, Version 2
TensorFlow Lite installer
To use a different runtime, you can use the recipe of this component as a template to create a custom
runtime component (p. 746).
Topics
• Versions (p. 340)
• Type (p. 340)
• Operating system (p. 340)
• Requirements (p. 340)
• Dependencies (p. 341)
• Configuration (p. 342)
• Usage (p. 343)
• Local log file (p. 343)
• Changelog (p. 344)
Versions
This component has the following versions:
• 2.5.x
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
Requirements
This component has the following requirements:
• On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, GNU C Library (glibc) version
2.27 or later installed on the device.
• On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device.
Run the following command to install the dependencies.
sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-
dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
• On Raspberry Pi devices, OpenCV-Python installed on the device. Run the following command to
install OpenCV-Python.
pip3 install opencv-python
340
AWS IoT Greengrass Developer Guide, Version 2
TensorFlow Lite installer
Endpoints and ports
By default, this component uses an installer script to install packages using the apt, yum, brew, and
pip commands, depending on what platform the core device uses. This component must be able to
perform outbound requests to various package indexes and repositories to run the installer script. To
allow this component's outbound traffic through a proxy or firewall, you must identify the endpoints for
the package indexes and repositories where your core device connects to install.
Consider the following when you identify endpoints required for this component's install script:
• The endpoints depend on the core device's platform. For example, a core device that runs Ubuntu
uses apt rather than yum or brew. Additionally, devices that use the same package index might have
different source lists, so they might retrieve packages from different repositories.
• The endpoints might differ between multiple devices that use the same package index, because each
device has its own source lists that define where to retrieve packages.
• The endpoints might change over time. Each package index provides the URLs of the repositories
where you download packages, and the owner of a package can change what URLs the package index
provides.
For more information about the dependencies that this component installs, and how to disable the
installer script, see the UseInstaller (p. 342) configuration parameter.
For more information about endpoints and ports required for basic operation, see Allow device traffic
through a proxy or firewall (p. 807).
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 344) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.5.5
The following table lists the dependencies for version 2.5.5 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.6.0 Soft
2.5.4 and 2.5.3
The following table lists the dependencies for versions 2.5.4 and 2.5.3 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Soft
2.5.2
The following table lists the dependencies for version 2.5.2 of this component.
341
AWS IoT Greengrass Developer Guide, Version 2
TensorFlow Lite installer
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Soft
2.5.1
The following table lists the dependencies for version 2.5.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Soft
2.5.0
The following table lists the dependencies for version 2.5.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.2.0 Soft
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
MLRootPath
(Optional) The path of the folder on Linux core devices where inference components read images
and write inference results. You can modify this value to any location on your device to which the
user running this component has read/write access.
Default: /greengrass/v2/work/variant.TensorFlowLite/greengrass_ml
WindowsMLRootPath
This feature is available in v1.6.6 and later of this component.
(Optional) The path of the folder on Windows core device where inference components read images
and write inference results. You can modify this value to any location on your device to which the
user running this component has read/write access.
Default: C:\greengrass\v2\work\variant.DLR\greengrass_ml
UseInstaller
(Optional) String value that defines whether to use the installer script in this component to install
TensorFlow Lite and its dependencies. Supported values are true and false.
Set this value to false if you want to use a custom script for TensorFlow Lite installation, or if you
want to include runtime dependencies in a pre-built Linux image. To use this component with the
AWS-provided TensorFlow Lite inference components, you will need to install the following libraries,
including any dependencies, and make them available the to default Greengrass system user.
• Python 3.8 or later, including pip for your version of Python
• TensorFlow Lite v2.5.0
342
AWS IoT Greengrass Developer Guide, Version 2
TensorFlow Lite installer
• NumPy
• OpenCV-Python
• AWS IoT Device SDK v2 for Python
• AWS Common Runtime (CRT) Python
• Picamera (for Raspberry Pi devices)
• awscam module (for AWS DeepLens devices)
Default: true
Usage
Use this component with the UseInstaller configuration parameter set to true to install TensorFlow
Lite and its dependencies on your device. The component sets up a virtual environment on your device
that includes the OpenCV and NumPy libraries that are required for TensorFlow Lite.
Note
The installer script in this component also installs the latest versions of additional system
libraries that are required to configure the virtual environment on your device and to use the
installed machine learning framework. This might upgrade the existing system libraries on
your device. Review the following table for the list of libraries that this component installs for
each supported operating system. If you want to customize this installation process, set the
UseInstaller configuration parameter to false, and develop your own installer script.
Platform Libraries installed on the Libraries installed in the virtual
device system environment
Armv7l build-essential, cmake, ca- setuptools, wheel
certificates, git
Amazon Linux 2 mesa-libGL None
Ubuntu wget None
When you deploy your inference component, this runtime component first verifies if your device already
has TensorFlow Lite and its dependencies installed. If not, then the runtime component installs them for
you.
Local log file
This component uses the following log file.
Linux
/greengrass/v2/logs/variant.TensorFlowLite.log
Windows
C:\greengrass\v2\logs\variant.TensorFlowLite.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
343
AWS IoT Greengrass Developer Guide, Version 2
Modbus-RTU protocol adapter
Linux
sudo tail -f /greengrass/v2/logs/variant.TensorFlowLite.log
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\variant.TensorFlowLite.log -Tail 10 -Wait
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.5.5 New feature
• Adds support for core devices that run Windows.
• Adds the new WindowsMLRootPath configuration parameter that you can
use to configure the inference results folder on Windows core devices.
2.5.4 New feature
• Add the new UseInstaller configuration parameter that lets you disable
the installation script in this component.
2.5.3 Version updated for Greengrass nucleus version 2.4.0 release.
2.5.2 Version updated for Greengrass nucleus version 2.3.0 release.
2.5.1 Version updated for Greengrass nucleus version 2.2.0 release.
2.5.0 Initial version.
Modbus-RTU protocol adapter
The Modbus-RTU protocol adapter component (aws.greengrass.Modbus) polls information from local
Modbus RTU devices.
To request information from a local Modbus RTU device with this component, publish a message to the
topic where this component subscribes. In the message, specify the Modbus RTU request to send to a
device. Then, this component publishes a response that contains the result of the Modbus RTU request.
Note
This component provides similar functionality to the Modbus RTU protocol adapter connector in
AWS IoT Greengrass V1. For more information, see Modbus RTU protocol adapter connector in
the AWS IoT Greengrass V1 Developer Guide.
Topics
• Versions (p. 345)
• Type (p. 345)
• Operating system (p. 345)
• Requirements (p. 345)
• Dependencies (p. 346)
344
AWS IoT Greengrass Developer Guide, Version 2
Versions
• Configuration (p. 348)
• Input data (p. 350)
• Output data (p. 351)
• Modbus RTU requests and responses (p. 353)
• Local log file (p. 359)
• Licenses (p. 359)
• Changelog (p. 359)
Versions
This component has the following versions:
• 2.0.x
Type
This component is a Lambda component (aws.greengrass.lambda). The Greengrass nucleus (p. 181)
runs this component's Lambda function using the Lambda launcher component (p. 252).
For more information, see Component types (p. 441).
Operating system
This component can be installed on Linux core devices only.
Requirements
This component has the following requirements:
• Your core device must meet the requirements to run Lambda functions. If you want the core device
to run containerized Lambda functions, the device must meet the requirements to do so. For more
information, see Lambda function requirements (p. 64).
• Python version 3.7 installed on the core device and added to the PATH environment variable.
• A physical connection between the AWS IoT Greengrass core device and the Modbus devices. The core
device must be physically connected to the Modbus RTU network through a serial port, such as a USB
port.
• To receive output data from this component, you must merge the following configuration update for
the legacy subscription router component (p. 260) when you deploy this component. The legacy
subscription router component (aws.greengrass.LegacySubscriptionRouter) is a dependency
of this component. This configuration specifies the topic where this component publishes responses.
Legacy subscription router v2.1.x
{
"subscriptions": {
"aws-greengrass-modbus": {
"id": "aws-greengrass-modbus",
"source": "component:aws.greengrass.Modbus",
"subject": "modbus/adapter/response",
"target": "cloud"
}
}
345
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
Legacy subscription router v2.0.x
{
"subscriptions": {
"aws-greengrass-modbus": {
"id": "aws-greengrass-modbus",
"source": "arn:aws:lambda:region:aws:function:aws-greengrass-modbus:version",
"subject": "modbus/adapter/response",
"target": "cloud"
}
}
}
• Replace region with the AWS Region that you use.
• Replace version with the version of the Lambda function that this component runs. To find
the Lambda function version, you must view the recipe for the version of this component that
you want to deploy. Open this component's details page in the AWS IoT Greengrass console, and
look for the Lambda function key-value pair. This key-value pair contains the name and version
of the Lambda function.
Important
You must update the Lambda function version on the legacy subscription router every
time you deploy this component. This ensures that you use the correct Lambda function
version for the component version that you deploy.
For more information, see Create deployments (p. 493).
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 359) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.0.8
The following table lists the dependencies for version 2.0.8 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.6.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.7
The following table lists the dependencies for version 2.0.7 of this component.
346
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.6
The following table lists the dependencies for version 2.0.6 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.5
The following table lists the dependencies for version 2.0.5 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.4
The following table lists the dependencies for version 2.0.4 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.2.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
347
AWS IoT Greengrass Developer Guide, Version 2
Configuration
2.0.3
The following table lists the dependencies for version 2.0.3 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.3 <2.1.0 Hard
Lambda launcher (p. 252) >=1.0.0 Hard
Lambda runtimes (p. 258) >=1.0.0 Soft
Token exchange >=1.0.0 Hard
service (p. 407)
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
Note
This component's default configuration includes Lambda function parameters. We recommend
that you edit only the following parameters to configure this component on your devices.
lambdaParams
An object that contains the parameters for this component's Lambda function. This object contains
the following information:
EnvironmentVariables
An object that contains the Lambda function's parameters. This object contains the following
information:
ModbusLocalPort
The absolute path to the physical Modbus serial port on the device, such as /dev/ttyS2.
To run this component in a container, you must define this path as a system
device (p. 349) that the component can access. This component runs in a container by
default.
Note
This component has read/write access to the device.
containerMode
(Optional) The containerization mode for this component. Choose from the following options:
• GreengrassContainer – The component runs in an isolated runtime environment inside the
AWS IoT Greengrass container.
If you specify this option, you specify a system device (p. 349) to give the container access to the
Modbus device.
• NoContainer – The component doesn't run in an isolated runtime environment.
Default: GreengrassContainer
348
AWS IoT Greengrass Developer Guide, Version 2
Configuration
containerParams
(Optional) An object that contains the container parameters for this component. The component
uses these parameters if you specify GreengrassContainer for containerMode.
This object contains the following information:
memorySize
(Optional) The amount of memory (in kilobytes) to allocate to the component.
Defaults to 512 MB (525,312 KB).
devices
(Optional) An object that specifies the system devices that the component can access in a
container.
Important
To run this component in a container, you must specify the system device that you
configure in the ModbusLocalPort environment variable.
This object contains the following information:
0 – This is an array index as a string.
An object that contains the following information:
path
The path to the system device on the core device. This must have the same value as the
value that you configure for ModbusLocalPort.
permission
(Optional) The permission to access the system device from the container. This value
must be rw, which specifies that the component has read/write access to the system
device.
Default: rw
addGroupOwner
(Optional) Whether or not to add the system group that runs the component as an
owner of the system device.
Default: true
pubsubTopics
(Optional) An object that contains the topics where the component subscribes to receive messages.
You can specify each topic and whether the component subscribes to MQTT topics from AWS IoT
Core or local publish/subscribe topics.
This object contains the following information:
0 – This is an array index as a string.
An object that contains the following information:
type
(Optional) The type of publish/subscribe messaging that this component uses to subscribe
to messages. Choose from the following options:
• Pubsub – Subscribe to local publish/subscribe messages. If you choose this option, the
topic can't contain MQTT wildcards. For more information about how to send messages
from custom component when you specify this option, see Publish/subscribe local
messages (p. 561).
349
AWS IoT Greengrass Developer Guide, Version 2
Input data
• IotCore – Subscribe to AWS IoT Core MQTT messages. If you choose this option, the
topic can contain MQTT wildcards. For more information about how to send messages
from custom components when you specify this option, see Publish/subscribe AWS IoT
Core MQTT messages (p. 586).
Default: Pubsub
topic
(Optional) The topic to which the component subscribes to receive messages. If you specify
IotCore for type, you can use MQTT wildcards (+ and #) in this topic.
Example Example: Configuration merge update (container mode)
{
"lambdaExecutionParameters": {
"EnvironmentVariables": {
"ModbusLocalPort": "/dev/ttyS2"
}
},
"containerMode": "GreengrassContainer",
"containerParams": {
"devices": {
"0": {
"path": "/dev/ttyS2",
"permission": "rw",
"addGroupOwner": true
}
}
}
}
Example Example: Configuration merge update (no container mode)
{
"lambdaExecutionParameters": {
"EnvironmentVariables": {
"ModbusLocalPort": "/dev/ttyS2"
}
},
"containerMode": "NoContainer"
}
Input data
This component accepts Modbus RTU request parameters on the following topic and sends the Modbus
RTU request to the device. By default, this component subscribes to local publish/subscribe messages.
For more information about how to publish messages to this component from your custom components,
see Publish/subscribe local messages (p. 561).
Default topic (local publish/subscribe): modbus/adapter/request
The message accepts the following properties. Input messages must be in JSON format.
request
The parameters for the Modbus RTU request to send.
The shape of the request message depends on the type of Modbus RTU request that it represents.
The following properties are required for all requests.
350
AWS IoT Greengrass Developer Guide, Version 2
Output data
Type: object that contains the following information:
operation
The name of the operation to run. For example, specify ReadCoilsRequest to read coils on
a Modbus RTU device. For more information about supported operations, see Modbus RTU
requests and responses (p. 353).
Type: string
device
The target device of the request.
This value must be an integer between 0 and 247.
Type: integer
The other parameters to include in the request depend on the operation. This component handles
the cyclic redundancy check (CRC) to verify data requests for you.
Note
If you request includes an address property, you must specify its value as an integer. For
example, "address": 1.
id
An arbitrary ID for the request. Use this property to map an input request to an output response.
When you specify this property, the component sets the id property in the response object to this
value.
Type: string
Example Example input: Read coils request
{
"request": {
"operation": "ReadCoilsRequest",
"device": 1,
"address": 1,
"count": 1
},
"id": "MyRequest"
}
Output data
This component publishes responses as output data on the following MQTT topic by default. You
must specify this topic as the subject in the configuration for the legacy subscription router
component (p. 260). For more information about how to subscribe to messages on this topic in your
custom components, see Publish/subscribe AWS IoT Core MQTT messages (p. 586).
Default topic (AWS IoT Core MQTT): modbus/adapter/response
The shape of the response message depends on the request operation and the response status. For
examples, see Example requests and responses (p. 353).
Every response includes the following properties:
response
The response from the Modbus RTU device.
351
AWS IoT Greengrass Developer Guide, Version 2
Output data
Type: object that contains the following information:
status
The status of the request. The status can be one of the following values:
• Success – The request was valid, the component sent the request to the Modbus RTU
network, and the Modbus RTU network returned a response.
• Exception – The request was valid, the component sent the request to the Modbus RTU
network, and the Modbus RTU network returned an exception. For more information, see
Response status: Exception (p. 358).
• No Response – The request was invalid, and the component caught the error before it sent
the request to the Modbus RTU network. For more information, see Response status: No
response (p. 358).
operation
The operation that the component requested.
device
The device where the component sent the request.
payload
The response from the Modbus RTU device. If the status is No Response, this object contains
only an error property with the description of the error (for example, [Input/Output] No
Response received from the remote unit).
id
The ID of the request, which you can use to identify which response corresponds to which request.
Note
A response for a write operation is simply an echo of the request. Although write responses
don't include meaningful information, it's a good practice to check the status of the response to
see if the request succeeds or fails.
Example Example output: Success
{
"response" : {
"status" : "success",
"device": 1,
"operation": "ReadCoilsRequest",
"payload": {
"function_code": 1,
"bits": [1]
}
},
"id" : "MyRequest"
}
Example Example output: Failure
{
"response" : {
"status" : "fail",
"error_message": "Internal Error",
"error": "Exception",
"device": 1,
"operation": "ReadCoilsRequest",
"payload": {
352
AWS IoT Greengrass Developer Guide, Version 2
Modbus RTU requests and responses
"function_code": 129,
"exception_code": 2
}
},
"id" : "MyRequest"
}
For more examples, see Example requests and responses (p. 353).
Modbus RTU requests and responses
This connector accepts Modbus RTU request parameters as input data (p. 350) and publishes responses
as output data (p. 351).
The following common operations are supported.
Operation name in request Function code in response
ReadCoilsRequest 01
ReadDiscreteInputsRequest 02
ReadHoldingRegistersRequest 03
ReadInputRegistersRequest 04
WriteSingleCoilRequest 05
WriteSingleRegisterRequest 06
WriteMultipleCoilsRequest 15
WriteMultipleRegistersRequest 16
MaskWriteRegisterRequest 22
ReadWriteMultipleRegistersRequest 23
Example requests and responses
The following are example requests and responses for supported operations.
Read coils
Request example:
{
"request": {
"operation": "ReadCoilsRequest",
"device": 1,
"address": 1,
"count": 1
},
"id": "TestRequest"
}
Response example:
353
AWS IoT Greengrass Developer Guide, Version 2
Modbus RTU requests and responses
"response": {
"status": "success",
"device": 1,
"operation": "ReadCoilsRequest",
"payload": {
"function_code": 1,
"bits": [1]
}
},
"id" : "TestRequest"
}
Read discrete inputs
Request example:
{
"request": {
"operation": "ReadDiscreteInputsRequest",
"device": 1,
"address": 1,
"count": 1
},
"id": "TestRequest"
}
Response example:
{
"response": {
"status": "success",
"device": 1,
"operation": "ReadDiscreteInputsRequest",
"payload": {
"function_code": 2,
"bits": [1]
}
},
"id" : "TestRequest"
}
Read holding registers
Request example:
{
"request": {
"operation": "ReadHoldingRegistersRequest",
"device": 1,
"address": 1,
"count": 1
},
"id": "TestRequest"
}
Response example:
{
"response": {
"status": "success",
"device": 1,
354
AWS IoT Greengrass Developer Guide, Version 2
Modbus RTU requests and responses
"operation": "ReadHoldingRegistersRequest",
"payload": {
"function_code": 3,
"registers": [20,30]
}
},
"id" : "TestRequest"
}
Read input registers
Request example:
{
"request": {
"operation": "ReadInputRegistersRequest",
"device": 1,
"address": 1,
"count": 1
},
"id": "TestRequest"
}
Write single coil
Request example:
{
"request": {
"operation": "WriteSingleCoilRequest",
"device": 1,
"address": 1,
"value": 1
},
"id": "TestRequest"
}
Response example:
{
"response": {
"status": "success",
"device": 1,
"operation": "WriteSingleCoilRequest",
"payload": {
"function_code": 5,
"address": 1,
"value": true
}
},
"id" : "TestRequest"
}
Write single register
Request example:
{
"request": {
"operation": "WriteSingleRegisterRequest",
"device": 1,
"address": 1,
355
AWS IoT Greengrass Developer Guide, Version 2
Modbus RTU requests and responses
"value": 1
},
"id": "TestRequest"
}
Write multiple coils
Request example:
{
"request": {
"operation": "WriteMultipleCoilsRequest",
"device": 1,
"address": 1,
"values": [1,0,0,1]
},
"id": "TestRequest"
}
Response example:
{
"response": {
"status": "success",
"device": 1,
"operation": "WriteMultipleCoilsRequest",
"payload": {
"function_code": 15,
"address": 1,
"count": 4
}
},
"id" : "TestRequest"
}
Write multiple registers
Request example:
{
"request": {
"operation": "WriteMultipleRegistersRequest",
"device": 1,
"address": 1,
"values": [20,30,10]
},
"id": "TestRequest"
}
Response example:
{
"response": {
"status": "success",
"device": 1,
"operation": "WriteMultipleRegistersRequest",
"payload": {
"function_code": 23,
"address": 1,
"count": 3
}
356
AWS IoT Greengrass Developer Guide, Version 2
Modbus RTU requests and responses
},
"id" : "TestRequest"
}
Mask write register
Request example:
{
"request": {
"operation": "MaskWriteRegisterRequest",
"device": 1,
"address": 1,
"and_mask": 175,
"or_mask": 1
},
"id": "TestRequest"
}
Response example:
{
"response": {
"status": "success",
"device": 1,
"operation": "MaskWriteRegisterRequest",
"payload": {
"function_code": 22,
"and_mask": 0,
"or_mask": 8
}
},
"id" : "TestRequest"
}
Read write multiple registers
Request example:
{
"request": {
"operation": "ReadWriteMultipleRegistersRequest",
"device": 1,
"read_address": 1,
"read_count": 2,
"write_address": 3,
"write_registers": [20,30,40]
},
"id": "TestRequest"
}
Response example:
{
"response": {
"status": "success",
"device": 1,
"operation": "ReadWriteMultipleRegistersRequest",
"payload": {
"function_code": 23,
"registers": [10,20,10,20]
}
357
AWS IoT Greengrass Developer Guide, Version 2
Modbus RTU requests and responses
},
"id" : "TestRequest"
}
Note
The response includes the registers that the component reads.
Response status: Exception
Exceptions can occur when the request format is valid, but the request is not completed successfully. In
this case, the response contains the following information:
• The status is set to Exception.
• The function_code equals the function code of the request + 128.
• The exception_code contains the exception code. For more information, see Modbus exception
codes.
Example:
{
"response": {
"status": "fail",
"error_message": "Internal Error",
"error": "Exception",
"device": 1,
"operation": "ReadCoilsRequest",
"payload": {
"function_code": 129,
"exception_code": 2
}
},
"id": "TestRequest"
}
Response status: No response
This connector performs validation checks on the Modbus request. For example, it checks for invalid
formats and missing fields. If the validation fails, the connector doesn't send the request. Instead, it
returns a response that contains the following information:
• The status is set to No Response.
• The error contains the error reason.
• The error_message contains the error message.
Examples:
{
"response": {
"status": "fail",
"error_message": "Invalid address field. Expected <type 'int'>, got <type 'str'>",
"error": "No Response",
"device": 1,
"operation": "ReadCoilsRequest",
"payload": {
"error": "Invalid address field. Expected Expected <type 'int'>, got <type 'str'>"
}
},
358
AWS IoT Greengrass Developer Guide, Version 2
Local log file
"id": "TestRequest"
}
If the request targets a nonexistent device or if the Modbus RTU network is not working, you might get a
ModbusIOException, which uses the No Response format.
{
"response": {
"status": "fail",
"error_message": "[Input/Output] No Response received from the remote unit",
"error": "No Response",
"device": 1,
"operation": "ReadCoilsRequest",
"payload": {
"error": "[Input/Output] No Response received from the remote unit"
}
},
"id": "TestRequest"
}
Local log file
This component uses the following log file.
/greengrass/v2/logs/aws.greengrass.Modbus.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 with the path to the AWS IoT Greengrass root folder.
sudo tail -f /greengrass/v2/logs/greengrass.log
Licenses
This component includes the following third-party software/licensing:
• pymodbus/BSD License
• pyserial/BSD License
This component is released under the Greengrass Core Software License Agreement.
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.0.8 Version updated for Greengrass nucleus version 2.5.0 release.
2.0.7 Version updated for Greengrass nucleus version 2.4.0 release.
2.0.6 Version updated for Greengrass nucleus version 2.3.0 release.
359
AWS IoT Greengrass Developer Guide, Version 2
MQTT bridge
Version Changes
2.0.5 Version updated for Greengrass nucleus version 2.2.0 release.
2.0.4 Version updated for Greengrass nucleus version 2.1.0 release.
2.0.3 Initial version.
MQTT bridge
The MQTT bridge component (aws.greengrass.clientdevices.mqtt.Bridge) relays MQTT
messages between client devices, local Greengrass publish/subscribe, and AWS IoT Core. You can use this
component to act on MQTT messages from client devices in custom components and sync client devices
with the AWS Cloud.
Note
Client devices are local IoT devices that connect to a Greengrass core device to send
MQTT messages and data to process. For more information, see Interact with local IoT
devices (p. 638).
You can use this component to relay messages between the following message brokers:
• Local MQTT – The local MQTT broker handles messages between client devices and a core device.
• Local publish/subscribe – The local Greengrass message broker handles messages between
components on a core device. For more information about how to interact with these messages in
Greengrass components, see Publish/subscribe local messages (p. 561).
• AWS IoT Core – The AWS IoT Core MQTT broker handles messages between IoT devices and AWS
Cloud destinations. For more information about how to interact with these messages in Greengrass
components, see Publish/subscribe AWS IoT Core MQTT messages (p. 586).
Note
The MQTT bridge uses QoS 1 to publish and subscribe to AWS IoT Core, even when a client
device uses QoS 0 to publish and subscribe to the local MQTT broker. As a result, you might
observe additional latency when you relay MQTT messages from client devices on the local
MQTT broker to AWS IoT Core. For more information about MQTT configuration on core
devices, see Configure MQTT timeouts and cache settings (p. 170).
Topics
• Versions (p. 360)
• Type (p. 361)
• Operating system (p. 361)
• Requirements (p. 361)
• Dependencies (p. 361)
• Configuration (p. 361)
• Local log file (p. 364)
• Changelog (p. 364)
Versions
This component has the following versions:
• 2.1.x
360
AWS IoT Greengrass Developer Guide, Version 2
Type
• 2.0.x
Type
This component is a plugin component (aws.greengrass.plugin). The Greengrass nucleus (p. 181)
runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when
you change this component's version on the core device.
This component uses the same log file as the Greengrass nucleus. For more information, see Monitor
AWS IoT Greengrass logs (p. 506).
For more information, see Component types (p. 441).
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
Requirements
This component has the following requirements:
• If you configure the core device's MQTT broker component to use a port other than the default port
8883, you must use MQTT bridge v2.1.0 or later. Configure it to connect on the port where the broker
operates.
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 364) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
The following table lists the dependencies for versions 2.1.x and 2.0.x of this component.
Dependency Compatible versions Dependency type
Client device auth (p. 194) >=2.0.0 <2.1.0 Hard
MQTT broker >=2.0.0 <2.1.0 Hard
(Moquette) (p. 365)
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
361
AWS IoT Greengrass Developer Guide, Version 2
Configuration
2.1.x
mqttTopicMapping
The topic mappings that you want to bridge. This component subscribes to messages on the
source topic and publishes the messages that it receives to the destination topic. Each topic
mapping defines the topic, source type, and destination type.
This object contains the following information:
topicMappingNameKey
The name of this topic mapping. Replace topicMappingNameKey with a name that helps
you identify this topic mapping.
This object contains the following information:
topic
The topic to bridge between the source and target brokers.
If you specify the LocalMqtt or IotCore source broker, you can use the + and #
MQTT topic wildcards to relay messages on all topics that match a topic filter. For more
information, see MQTT topics in the AWS IoT Core Developer Guide.
source
The source message broker. Choose from the following options:
• LocalMqtt – The local MQTT broker where client devices communicate.
• Pubsub – The local Greengrass publish/subscribe message broker.
• IotCore – The AWS IoT Core MQTT message broker.
Note
The MQTT bridge uses QoS 1 to publish and subscribe to AWS IoT Core, even
when a client device uses QoS 0 to publish and subscribe to the local MQTT
broker. As a result, you might observe additional latency when you relay
MQTT messages from client devices on the local MQTT broker to AWS IoT
Core. For more information about MQTT configuration on core devices, see
Configure MQTT timeouts and cache settings (p. 170).
source and target must be different.
target
The target message broker. Choose from the following options:
• LocalMqtt – The local MQTT broker where client devices communicate.
• Pubsub – The local Greengrass publish/subscribe message broker.
• IotCore – The AWS IoT Core MQTT message broker.
Note
The MQTT bridge uses QoS 1 to publish and subscribe to AWS IoT Core, even
when a client device uses QoS 0 to publish and subscribe to the local MQTT
broker. As a result, you might observe additional latency when you relay
MQTT messages from client devices on the local MQTT broker to AWS IoT
Core. For more information about MQTT configuration on core devices, see
Configure MQTT timeouts and cache settings (p. 170).
source and target must be different.
brokerUri
(Optional) The URI of the local MQTT broker. You must specify this parameter if you configure
the MQTT broker to use a different port than the default port 8883. Use the following format,
and replace port with the port where the MQTT broker operates: ssl://localhost:port.
362
AWS IoT Greengrass Developer Guide, Version 2
Configuration
Default: ssl://localhost:8883
2.0.x
mqttTopicMapping
The topic mappings that you want to bridge. This component subscribes to messages on the
source topic and publishes the messages that it receives to the destination topic. Each topic
mapping defines the topic, source type, and destination type.
This object contains the following information:
topicMappingNameKey
The name of this topic mapping. Replace topicMappingNameKey with a name that helps
you identify this topic mapping.
This object contains the following information:
topic
The topic to bridge between the source and target brokers.
If you specify the LocalMqtt or IotCore source broker, you can use the + and #
MQTT topic wildcards to relay messages on all topics that match a topic filter. For more
information, see MQTT topics in the AWS IoT Core Developer Guide.
source
The source message broker. Choose from the following options:
• LocalMqtt – The local MQTT broker where client devices communicate.
• Pubsub – The local Greengrass publish/subscribe message broker.
• IotCore – The AWS IoT Core MQTT message broker.
Note
The MQTT bridge uses QoS 1 to publish and subscribe to AWS IoT Core, even
when a client device uses QoS 0 to publish and subscribe to the local MQTT
broker. As a result, you might observe additional latency when you relay
MQTT messages from client devices on the local MQTT broker to AWS IoT
Core. For more information about MQTT configuration on core devices, see
Configure MQTT timeouts and cache settings (p. 170).
source and target must be different.
target
The target message broker. Choose from the following options:
• LocalMqtt – The local MQTT broker where client devices communicate.
• Pubsub – The local Greengrass publish/subscribe message broker.
• IotCore – The AWS IoT Core MQTT message broker.
Note
The MQTT bridge uses QoS 1 to publish and subscribe to AWS IoT Core, even
when a client device uses QoS 0 to publish and subscribe to the local MQTT
broker. As a result, you might observe additional latency when you relay
MQTT messages from client devices on the local MQTT broker to AWS IoT
Core. For more information about MQTT configuration on core devices, see
Configure MQTT timeouts and cache settings (p. 170).
363
AWS IoT Greengrass Developer Guide, Version 2
Local log file
source and target must be different.
Example Example: Configuration merge update
The following example configuration update specifies to sync the clients/MyClientDevice1/
hello/world and clients/MyClientDevice2/hello/world topics between client devices and AWS
IoT Core.
{
"mqttTopicMapping": {
"ClientDevice1Mapping": {
"topic": "clients/MyClientDevice1/hello/world",
"source": "LocalMqtt",
"target": "IotCore"
},
"ClientDevice2Mapping": {
"topic": "clients/MyClientDevice2/hello/world",
"source": "LocalMqtt",
"target": "IotCore"
}
}
}
Local log file
This component uses the same log file as the Greengrass nucleus (p. 181) component.
Linux
/greengrass/v2/logs/greengrass.log
Windows
C:\greengrass\v2\logs\greengrass.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
Linux
sudo tail -f /greengrass/v2/logs/greengrass.log
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
Changelog
The following table describes the changes in each version of the component.
364
AWS IoT Greengrass Developer Guide, Version 2
MQTT broker (Moquette)
Version Changes
2.1.0 Improvements
• Adds the brokerUri parameter, which enables you to use a non-default
MQTT broker port.
2.0.1 Version updated for Greengrass nucleus version 2.4.0 release.
2.0.0 Initial version.
MQTT broker (Moquette)
The Moquette MQTT broker component (aws.greengrass.clientdevices.mqtt.Moquette)
handles MQTT messages between client devices and a Greengrass core device. This component provides
a modified version of the Moquette MQTT broker.
This broker implements the MQTT 3.1.1 protocol. It includes support for QoS 0, QoS 1, QoS 2 retained
messages, last will messages, and persistent sessions.
Note
Client devices are local IoT devices that connect to a Greengrass core device to send
MQTT messages and data to process. For more information, see Interact with local IoT
devices (p. 638).
Topics
• Versions (p. 365)
• Type (p. 365)
• Operating system (p. 366)
• Requirements (p. 366)
• Dependencies (p. 366)
• Configuration (p. 366)
• Local log file (p. 367)
• Changelog (p. 368)
Versions
This component has the following versions:
• 2.0.x
Type
This component is a plugin component (aws.greengrass.plugin). The Greengrass nucleus (p. 181)
runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when
you change this component's version on the core device.
This component uses the same log file as the Greengrass nucleus. For more information, see Monitor
AWS IoT Greengrass logs (p. 506).
For more information, see Component types (p. 441).
365
AWS IoT Greengrass Developer Guide, Version 2
Operating system
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
Requirements
This component has the following requirements:
• The core device must be able to accept connections on the port where the MQTT broker operates. This
component runs the MQTT broker on port 8883 by default. You can specify a different port when you
configure this component.
If you specify a different port, and you use the MQTT bridge component (p. 360) to relay MQTT
messages to other brokers, you must use MQTT bridge v2.1.0 or later. Configure it to use the port
where the MQTT broker operates.
If you specify a different port, and you use the IP detector component (p. 240) to manage MQTT
broker endpoints, you must use IP detector v2.1.0 or later. Configure it to report the port where the
MQTT broker operates.
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 368) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
The following table lists the dependencies for version 2.0.x of this component.
Dependency Compatible versions Dependency type
Client device auth (p. 194) >=2.0.0 <2.1.0 Hard
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
moquette
(Optional) The Moquette MQTT broker configuration to use. You can configure a subset of Moqeutte
configuration options in this component. For more information, see the inline comments in the
Moquette configuration file.
This object contains the following information:
366
AWS IoT Greengrass Developer Guide, Version 2
Local log file
ssl_port
(Optional) The port where the MQTT broker operates.
Note
If you specify a different port, and you use the MQTT bridge component (p. 360)
to relay MQTT messages to other brokers, you must use MQTT bridge v2.1.0 or later.
Configure it to use the port where the MQTT broker operates.
If you specify a different port, and you use the IP detector component (p. 240) to
manage MQTT broker endpoints, you must use IP detector v2.1.0 or later. Configure it
to report the port where the MQTT broker operates.
Default: 8883
host
(Optional) The interface where the MQTT broker binds. For example, you might change this
parameter so that the MQTT broker binds only to a specific local network.
Default: 0.0.0.0 (binds to all network interfaces)
Example Example: Configuration merge update
The following example configuration specifies to operate the MQTT broker on port 443.
{
"moquette": {
"ssl_port": "443"
}
}
Local log file
This component uses the same log file as the Greengrass nucleus (p. 181) component.
Linux
/greengrass/v2/logs/greengrass.log
Windows
C:\greengrass\v2\logs\greengrass.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
Linux
sudo tail -f /greengrass/v2/logs/greengrass.log
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
367
AWS IoT Greengrass Developer Guide, Version 2
Changelog
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.0.2 Bug fixes and improvements
• Increases the maximum MQTT message size from 8,092 bytes to 128
kilobytes. The effective MQTT message payload limit is slightly less,
because the message size limit includes message headers.
• Adds support for integer values in the ssl_port parameter.
2.0.1 Version updated for Greengrass nucleus version 2.4.0 release.
2.0.0 Initial version.
Nucleus telemetry emitter
The nucleus emitter component (aws.greengrass.telemetry.NucleusEmitter) gathers system
health telemetry data and publishes it continually to a local topic and an AWS IoT Core MQTT topic.
This component enables you to gather real-time system telemetry on your Greengrass core devices. For
information about the Greengrass telemetry agent that publishes system telemetry data to Amazon
EventBridge, see Gather system health telemetry data from AWS IoT Greengrass core devices (p. 515).
Topics
• Versions (p. 368)
• Type (p. 368)
• Operating system (p. 369)
• Dependencies (p. 369)
• Configuration (p. 369)
• Output data (p. 370)
• Usage (p. 373)
• Local log file (p. 373)
• Changelog (p. 374)
Versions
This component has the following versions:
• 1.0.x
Type
This component is a plugin component (aws.greengrass.plugin). The Greengrass nucleus (p. 181)
runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when
you change this component's version on the core device.
This component uses the same log file as the Greengrass nucleus. For more information, see Monitor
AWS IoT Greengrass logs (p. 506).
368
AWS IoT Greengrass Developer Guide, Version 2
Operating system
For more information, see Component types (p. 441).
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 374) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
1.0.1
The following table lists the dependencies for version 1.0.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.4.0 <2.6.0 Hard
1.0.0
The following table lists the dependencies for version 1.0.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.4.0 <2.5.0 Hard
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
pubSubPublish
(Optional) Defines whether to publish telemetry data to the $local/greengrass/telemetry
topic. Supported values are true and false.
Default: true
mqttTopic
(Optional) The AWS IoT Core MQTT topic to which this component publishes telemetry data.
Set this value to the AWS IoT Core MQTT topic to which you want to publish telemetry data. When
this value is empty, the nucleus emitter doesn't publish telemetry data to the cloud.
369
AWS IoT Greengrass Developer Guide, Version 2
Output data
Default: ""
telemetryPublishIntervalMs
(Optional) The amount of time (in milliseconds) between which the component publishes telemetry
data. If you set this value lower than the minimum supported value, the component uses the
minimum value instead.
Minimum: 500
Default: 60000
Note
Lower publish intervals result in higher CPU usage on your core device. We recommend that
you start with the default publish interval and adjust it based on your device's CPU usage.
Example Example: Configuration merge update
The following example shows a sample configuration merge update that enables publishing telemetry
data every 5 seconds to the $local/greengrass/telemetry topic and the greengrass/
myTelemetry AWS IoT Core MQTT topic.
{
"pubSubPublish": "true",
"mqttTopic": "greengrass/myTelemetry",
"telemetryPublishIntervalMs": 5000
}
Output data
This component publishes telemetry metrics as a JSON array on the following topic.
Local topic: $local/greengrass/telemetry
You can optionally choose to also publish telemetry metrics to an AWS IoT Core MQTT topic. For more
information about topics, see MQTT topics in the AWS IoT Core Developer Guide.
Example Example data
[
{
"A": "Average",
"N": "CpuUsage",
"NS": "SystemMetrics",
"TS": 1627597331445,
"U": "Percent",
"V": 26.21981271562346
},
{
"A": "Count",
"N": "TotalNumberOfFDs",
"NS": "SystemMetrics",
"TS": 1627597331445,
"U": "Count",
"V": 7316
},
{
"A": "Count",
"N": "SystemMemUsage",
370
AWS IoT Greengrass Developer Guide, Version 2
Output data
"NS": "SystemMetrics",
"TS": 1627597331445,
"U": "Megabytes",
"V": 10098
},
{
"A": "Count",
"N": "NumberOfComponentsStarting",
"NS": "GreengrassComponents",
"TS": 1627597331446,
"U": "Count",
"V": 0
},
{
"A": "Count",
"N": "NumberOfComponentsInstalled",
"NS": "GreengrassComponents",
"TS": 1627597331446,
"U": "Count",
"V": 0
},
{
"A": "Count",
"N": "NumberOfComponentsStateless",
"NS": "GreengrassComponents",
"TS": 1627597331446,
"U": "Count",
"V": 0
},
{
"A": "Count",
"N": "NumberOfComponentsStopping",
"NS": "GreengrassComponents",
"TS": 1627597331446,
"U": "Count",
"V": 0
},
{
"A": "Count",
"N": "NumberOfComponentsBroken",
"NS": "GreengrassComponents",
"TS": 1627597331446,
"U": "Count",
"V": 0
},
{
"A": "Count",
"N": "NumberOfComponentsRunning",
"NS": "GreengrassComponents",
"TS": 1627597331446,
"U": "Count",
"V": 7
},
{
"A": "Count",
"N": "NumberOfComponentsErrored",
"NS": "GreengrassComponents",
"TS": 1627597331446,
"U": "Count",
"V": 0
},
{
"A": "Count",
"N": "NumberOfComponentsNew",
"NS": "GreengrassComponents",
"TS": 1627597331446,
371
AWS IoT Greengrass Developer Guide, Version 2
Output data
"U": "Count",
"V": 0
},
{
"A": "Count",
"N": "NumberOfComponentsFinished",
"NS": "GreengrassComponents",
"TS": 1627597331446,
"U": "Count",
"V": 2
}
]
The output array contains a list of metrics that have the following properties:
The aggregation type for the metric.
For the CpuUsage metric, this property is set to Average because the published value of the metric
is the average CPU usage amount since the last publish event.
For all other metrics, the nucleus emitter doesn't aggregate the metric value, and this property is set
to Count.
N
The name of the metric.
NS
The metric namespace.
TS
The timestamp of when the data was gathered.
U
The unit of the metric value.
V
The metric value.
The nucleus emitter publishes the following metrics:
Name Description Source
SystemMemUsage The amount of memory System
currently in use by all
applications on the Greengrass
core device, including the
operating system.
CpuUsage The amount of CPU currently System
in use by all applications on
the Greengrass core device,
including the operating system.
TotalNumberOfFDs The number of file descriptors System
stored by the operating system
of the Greengrass core device.
372
AWS IoT Greengrass Developer Guide, Version 2
Usage
Name Description Source
One file descriptor uniquely
identifies one open file.
NumberOfComponentsRunning The number of components that Greengrass nucleus
are running on the Greengrass
core device.
NumberOfComponentsErrored The number of components Greengrass nucleus
that are in error state on the
Greengrass core device.
NumberOfComponentsInstalledThe number of components that Greengrass nucleus
are installed on the Greengrass
core device.
NumberOfComponentsStarting The number of components that Greengrass nucleus
are starting on the Greengrass
core device.
NumberOfComponentsNew The number of components that Greengrass nucleus
are new on the Greengrass core
device.
NumberOfComponentsStopping The number of components that Greengrass nucleus
are stopping on the Greengrass
core device.
NumberOfComponentsFinished The number of components that Greengrass nucleus
are finished on the Greengrass
core device.
NumberOfComponentsBroken The number of components that Greengrass nucleus
are broken on the Greengrass
core device.
NumberOfComponentsStatelessThe number of components that Greengrass nucleus
are stateless on the Greengrass
core device.
Usage
To use system health telemetry data, you can create custom components that subscribe to the topics
to which the nucleus emitter publishes the telemetry data, and react to that data as needed. Because
the nucleus emitter component provides the option to publish telemetry data to a local topic, you can
subscribe to that topic, and use the published data to act locally on your core device. The core device can
then react to telemetry data even when it has limited connectivity to the cloud.
For example, you can configure a component that listens on the $local/greengrass/telemetry
topic for telemetry data and send the data to the stream manager component to stream your data to
the AWS Cloud. For more information about creating such a component, see Publish/subscribe local
messages (p. 561) and Create custom components that use stream manager (p. 684).
Local log file
This component uses the same log file as the Greengrass nucleus (p. 181) component.
373
AWS IoT Greengrass Developer Guide, Version 2
Changelog
Linux
/greengrass/v2/logs/greengrass.log
Windows
C:\greengrass\v2\logs\greengrass.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
Linux
sudo tail -f /greengrass/v2/logs/greengrass.log
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
Changelog
The following table describes the changes in each version of the component.
Version Changes
1.0.1 Version updated for Greengrass nucleus version 2.5.0 release.
1.0.0 Initial version.
Secret manager
The secret manager component (aws.greengrass.SecretManager) deploys secrets from AWS Secrets
Manager to Greengrass core devices. Use this component to securely use credentials, such as passwords,
in custom components on your Greengrass core devices. For more information about Secrets Manager,
see What is AWS Secrets Manager? in the AWS Secrets Manager User Guide.
To access this component's secrets in your custom Greengrass components, use the
GetSecretValue (p. 611) operation in the AWS IoT Device SDK. For more information, see Use the
AWS IoT Device SDK to communicate with the Greengrass nucleus, other components, and AWS IoT
Core (p. 545) and Retrieve secret values (p. 610).
This component encrypts secrets on the core device to keep your credentials and passwords secure until
you need to use them.
Topics
• Versions (p. 375)
• Type (p. 375)
374
AWS IoT Greengrass Developer Guide, Version 2
Versions
• Operating system (p. 375)
• Requirements (p. 375)
• Dependencies (p. 376)
• Configuration (p. 377)
• Local log file (p. 378)
• Changelog (p. 378)
Versions
This component has the following versions:
• 2.1.x
• 2.0.x
Type
This component is a plugin component (aws.greengrass.plugin). The Greengrass nucleus (p. 181)
runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when
you change this component's version on the core device.
This component uses the same log file as the Greengrass nucleus. For more information, see Monitor
AWS IoT Greengrass logs (p. 506).
For more information, see Component types (p. 441).
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
Requirements
This component has the following requirements:
• The Greengrass device role (p. 790) must allow the secretsmanager:GetSecretValue action, as
shown in the following example IAM policy.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"secretsmanager:GetSecretValue"
],
"Effect": "Allow",
"Resource": [
"arn:aws:secretsmanager:region:123456789012:secret:MySecret"
]
}
]
}
375
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
Note
If you use a customer-managed AWS Key Management Service key to encrypt secrets, the
device role must also allow the kms:Decrypt action.
For more information about IAM policies for Secrets Manager, see the following in the AWS Secrets
Manager User Guide:
• Authentication and access control for AWS Secrets Manager
• Actions, resources, and context keys you can use in an IAM policy or secret policy for AWS Secrets
Manager
• Custom components must define an authorization policy that allows
aws.greengrass#GetSecretValue to get secrets that you store with this component. In this
authorization policy, you can restrict components' access to specific secrets. For more information, see
secret manager IPC authorization (p. 611).
Endpoints and ports
This component must be able to perform outbound requests to the following endpoints and ports, in
addition to endpoints and ports required for basic operation. For more information, see Allow device
traffic through a proxy or firewall (p. 807).
Endpoint Port Required Description
443
secretsmanager.region.amazonaws.com Yes Download
secrets to
the core
device.
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 378) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.1.0
The following table lists the dependencies for version 2.1.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.5.0 <2.6.0 Soft
2.0.9
The following table lists the dependencies for version 2.0.9 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Soft
376
AWS IoT Greengrass Developer Guide, Version 2
Configuration
2.0.8
The following table lists the dependencies for version 2.0.8 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Soft
2.0.7
The following table lists the dependencies for version 2.0.7 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Soft
2.0.6
The following table lists the dependencies for version 2.0.6 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.2.0 Soft
2.0.4 and 2.0.5
The following table lists the dependencies for versions 2.0.4 and 2.0.5 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.3 <2.1.0 Soft
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
cloudSecrets
A list of Secrets Manager secrets to deploy to the core device. You can specify labels to define which
versions of each secret to deploy. If you don't specify a version, this component deploys the version
with the staging label AWSCURRENT attached. For more information, see Staging labels in the AWS
Secrets Manager User Guide.
Each object contains the following information:
arn
The ARN of the secret to deploy.
377
AWS IoT Greengrass Developer Guide, Version 2
Local log file
labels
(Optional) A list of labels to identify the versions of the secret to deploy to the core device.
Each label must be a string.
Example Example: Configuration merge update
{
"cloudSecrets": [
{
"arn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyGreengrassSecret-
abcdef"
}
]
}
Local log file
This component uses the same log file as the Greengrass nucleus (p. 181) component.
Linux
/greengrass/v2/logs/greengrass.log
Windows
C:\greengrass\v2\logs\greengrass.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
Linux
sudo tail -f /greengrass/v2/logs/greengrass.log
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.1.0 Version updated for Greengrass nucleus version 2.5.0 release.
2.0.9 Version updated for Greengrass nucleus version 2.4.0 release.
378
AWS IoT Greengrass Developer Guide, Version 2
Secure tunneling
Version Changes
2.0.8 Version updated for Greengrass nucleus version 2.3.0 release.
2.0.7 Version updated for Greengrass nucleus version 2.2.0 release.
2.0.6 Version updated for Greengrass nucleus version 2.1.0 release.
2.0.5 Improvements
• Add support for AWS China Regions and AWS GovCloud (US) Regions.
2.0.4 Initial version.
Secure tunneling
The secure tunneling component (aws.greengrass.SecureTunneling) enables you to use AWS IoT
secure tunneling to establish secure bidirectional communication with a Greengrass core device that is
behind restricted firewalls.
For example, a Greengrass core device is behind a firewall that prohibits all incoming connections, which
blocks SSH connections to the device. Secure tunneling uses MQTT over WebSockets to make these
connections so that you can open an SSH connection to the device by using a tunnel that is managed by
AWS IoT. For more information about using AWS IoT secure tunneling to connect to remote devices, see
AWS IoT secure tunneling in the AWS IoT Developer Guide.
This component subscribes to the AWS IoT Core MQTT message broker on the $aws/
things/greengrass-core-device/tunnels/notify topic to receive secure tunneling notifications.
Topics
• Versions (p. 379)
• Type (p. 379)
• Operating system (p. 380)
• Requirements (p. 380)
• Dependencies (p. 380)
• Configuration (p. 381)
• Local log file (p. 382)
• Licenses (p. 383)
• See also (p. 383)
• Changelog (p. 383)
Versions
This component has the following versions:
• 1.0.x
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
379
AWS IoT Greengrass Developer Guide, Version 2
Operating system
For more information, see Component types (p. 441).
Operating system
This component can be installed on Linux core devices only.
Requirements
This component has the following requirements:
• Python 3.5 or later installed on the Greengrass core device and added to the PATH environment
variable.
• libcrypto.so.1.1 installed on the Greengrass core device and added to the PATH environment
variable.
• The Greengrass core device must allow outbound traffic on port 443.
• The Greengrass core device must have enabled the service that you want to use to communicate with
the device. For example, to open an SSH connection to the device, the device must have SSH enabled.
Endpoints and ports
This component must be able to perform outbound requests to the following endpoints and ports, in
addition to endpoints and ports required for basic operation. For more information, see Allow device
traffic through a proxy or firewall (p. 807).
Endpoint Port Required Description
443
data.tunneling.iot.region.amazonaws.com Yes Establish
secure
tunnels.
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 383) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
1.0.5
The following table lists the dependencies for version 1.0.5 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.6.0 Soft
1.0.4
The following table lists the dependencies for version 1.0.4 of this component.
380
AWS IoT Greengrass Developer Guide, Version 2
Configuration
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Soft
1.0.3
The following table lists the dependencies for version 1.0.3 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Soft
1.0.2
The following table lists the dependencies for version 1.0.2 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Soft
1.0.1
The following table lists the dependencies for version 1.0.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.2.0 Soft
1.0.0
The following table lists the dependencies for version 1.0.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.3 <2.1.0 Soft
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
OS_DIST_INFO
(Optional) The operating system of your core device. By default, the component attempts to
automatically identify the operating system running on your core device. If the component fails
381
AWS IoT Greengrass Developer Guide, Version 2
Local log file
to start with the default value, then use this value to specify the operating system. For a list of
supported operating systems for this component, see Device requirements (p. 63).
This value can be one of the following: auto, ubuntu, amzn2, raspberrypi.
Default: auto
accessControl
(Optional) The object that contains the authorization policy (p. 552) that allows the component to
subscribe to the secure tunneling notifications topic.
Note
Do not modify this configuration parameter if your deployment targets a thing group.
If your deployment targets an individual core device, and you want to restrict this
component's subscription to the topic for that device, then in the resources value in the
authorization policy, replace the MQTT topic wildcard (+) with the thing name for that core
device.
Default:
{
"aws.greengrass.ipc.mqttproxy": {
"aws.iot.SecureTunneling:mqttproxy:1": {
"policyDescription": "Access to tunnel notification pubsub topic",
"operations": [
"aws.greengrass#SubscribeToIoTCore"
],
"resources": [
"$aws/things/+/tunnels/notify"
]
}
}
}
Example Example: Configuration merge update
The following example configuration specifies to allow this component to open secure tunnels on a core
device named MyGreengrassCore that runs Ubuntu.
{
"OS_DIST_INFO": "ubuntu",
"accessControl": {
"aws.greengrass.ipc.mqttproxy": {
"aws.iot.SecureTunneling:mqttproxy:1": {
"policyDescription": "Access to tunnel notification pubsub topic",
"operations": [
"aws.greengrass#SubscribeToIoTCore"
],
"resources": [
"$aws/things/MyGreengrassCore/tunnels/notify"
]
}
}
}
}
Local log file
This component uses the following log file.
382
AWS IoT Greengrass Developer Guide, Version 2
Licenses
/greengrass/v2/logs/aws.greengrass.SecureTunneling.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 with the path to the AWS IoT Greengrass root folder.
sudo tail -f /greengrass/v2/logs/greengrass.log
Licenses
This component includes the following third-party software/licensing:
• AWS IoT Device Client/Apache License 2.0
• AWS IoT Device SDK for Java/Apache License 2.0
• gson/Apache License 2.0
• log4j/Apache License 2.0
• slf4j/Apache License 2.0
See also
• AWS IoT secure tunneling in the AWS IoT Developer Guide.
Changelog
The following table describes the changes in each version of the component.
Version Changes
1.0.5 Version updated for Greengrass nucleus version 2.5.0 release.
1.0.4 Version updated for Greengrass nucleus version 2.4.0 release.
1.0.3 Version updated for Greengrass nucleus version 2.3.0 release.
1.0.2 Version updated for Greengrass nucleus version 2.2.0 release.
1.0.1 Version updated for Greengrass nucleus version 2.1.0 release.
1.0.0 Initial version.
Shadow manager
The shadow manager component (aws.greengrass.ShadowManager) enables the local shadow
service on your core device. The local shadow service allows components to use interprocess
communication to interact with local shadows (p. 618). The shadow manager component manages the
storage of local shadow documents, and also handles synchronization of local shadow states with the
AWS IoT Device Shadow service.
383
AWS IoT Greengrass Developer Guide, Version 2
Versions
For more information about how AWS IoT Greengrass devices can interact with shadows, see Interact
with device shadows (p. 678).
Topics
• Versions (p. 384)
• Type (p. 384)
• Operating system (p. 384)
• Requirements (p. 384)
• Dependencies (p. 385)
• Configuration (p. 385)
• Local log file (p. 388)
• Changelog (p. 388)
Versions
This component has the following versions:
• 2.0.x
Type
This component is a plugin component (aws.greengrass.plugin). The Greengrass nucleus (p. 181)
runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when
you change this component's version on the core device.
This component uses the same log file as the Greengrass nucleus. For more information, see Monitor
AWS IoT Greengrass logs (p. 506).
For more information, see Component types (p. 441).
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
Requirements
This component has the following requirements:
• The Greengrass core device's AWS IoT policy configured to allow the following AWS IoT Core shadow
policy actions that are required to sync shadows to the AWS IoT Device Shadow service.
• iot:GetThingShadow
• iot:UpdateThingShadow
• iot:DeleteThingShadow
For more information about these AWS IoT Core policies, see AWS IoT Core policy actions in the AWS
IoT Developer Guide.
384
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
For more information about the minimal AWS IoT policy, see Minimal AWS IoT policy for AWS IoT
Greengrass V2 core devices (p. 777)
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 388) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.0.5
The following table lists the dependencies for version 2.0.5 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.2.0 <2.6.0 Soft
2.0.3 and 2.0.4
The following table lists the dependencies for versions 2.0.3 and 2.0.4 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.2.0 <2.5.0 Soft
2.0.1 and 2.0.2
The following table lists the dependencies for versions 2.0.1 and 2.0.2 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.2.0 <2.4.0 Soft
2.0.0
The following table lists the dependencies for version 2.0.0 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.2.0 <2.3.0 Soft
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
385
AWS IoT Greengrass Developer Guide, Version 2
Configuration
synchronize
(Optional) The synchronization settings that determine how shadows are synced with the AWS
Cloud.
Note
You must create a configuration update with this property if you want to enable syncing
shadows with the AWS Cloud.
This object contains the following information.
coreThing
The core device shadows to sync. This object contains the following information.
classic
By default, the shadow manager syncs the local state of the classic shadow for your core
device with the AWS Cloud. If you don't want to sync the classic device shadow, set this to
false.
Default: true
namedShadows
The list of named core device shadows that you want to sync.
Warning
The AWS IoT Greengrass service uses the
AWSManagedGreengrassV2Deployment named shadow to manage deployments
that target individual core devices. This named shadow is reserved for use by the
AWS IoT Greengrass service. Do not update or delete this named shadow.
shadowDocuments
The list of additional device shadows to sync. Each object in this list contains the following
information.
thingName
The thing name of the device for which to sync shadows.
classic
If you don't want to sync the classic device shadow for the thingName device, set this to
false.
Default: true
namedShadows
The list of named device shadows that you want to sync.
rateLimits
The settings that determine the rate limits for shadow service requests.
This object contains the following information.
maxOutboundSyncUpdatesPerSecond
The maximum number of sync requests per second that the device transmits.
Default: 100 requests/second
maxTotalLocalRequestsRate
The maximum number of local IPC requests per second that are sent to the core device.
386
AWS IoT Greengrass Developer Guide, Version 2
Configuration
Default: 200 requests/second
maxLocalRequestsPerSecondPerThing
The maximum number of local IPC requests per second that are sent for each connected IoT
thing.
Default: 20 requests/second for each thing
Note
These rate limits parameters define the maximum number of requests per second for the
local shadow service. The maximum number of requests per second for the AWS IoT Device
Shadow service depends on your AWS Region. For more information, see the limits for the
AWS IoT Device Shadow Service API in the Amazon Web Services General Reference.
shadowDocumentSizeLimitBytes
The maximum allowed size of each JSON state document for local shadows.
If you increase this value, you must also increase the resource limit for the JSON state document for
cloud shadows. For more information, see the limits for the AWS IoT Device Shadow Service API in
the Amazon Web Services General Reference.
Default: 8192 bytes
Maximum: 30720 bytes
Example Example: Configuration merge update
The following example shows a sample configuration merge update with all available configuration
parameters for the shadow manager component.
{
"synchronize": {
"coreThing": {
"classic": true,
"namedShadows": [
"MyCoreShadowA",
"MyCoreShadowB"
]
},
"shadowDocuments": [
{
"thingName": "MyDevice1",
"classic": false,
"namedShadows": [
"MyShadowA",
"MyShadowB"
]
},
{
"thingName": "MyDevice2",
"classic": true,
"namedShadows": []
}
]
},
"rateLimits": {
"maxOutboundSyncUpdatesPerSecond": 100,
"maxTotalLocalRequestsRate": 200,
"maxLocalRequestsPerSecondPerThing": 20
},
"shadowDocumentSizeLimitBytes": 8192
387
AWS IoT Greengrass Developer Guide, Version 2
Local log file
Local log file
This component uses the same log file as the Greengrass nucleus (p. 181) component.
Linux
/greengrass/v2/logs/greengrass.log
Windows
C:\greengrass\v2\logs\greengrass.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
Linux
sudo tail -f /greengrass/v2/logs/greengrass.log
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.0.5 Version updated for Greengrass nucleus version 2.5.0 release.
2.0.4 Bug fixes and improvements
• Fixes an issue that caused shadow manager to delete newly created
versions of any shadow that was previously deleted.
• Updates the DeleteThingShadow IPC operation to increment the shadow
version when called.
2.0.3 Version updated for Greengrass nucleus version 2.4.0 release.
2.0.2 Bug fixes and improvements
• Fixed an issue that caused shadow manager to not recognize the delta
property when syncing shadow states from AWS IoT Core.
• Fixed an issue that sometimes caused sync requests for a shadow to be
merged incorrectly.
2.0.1 Version updated for Greengrass nucleus version 2.3.0 release.
388
AWS IoT Greengrass Developer Guide, Version 2
Amazon SNS
Version Changes
2.0.0 Initial version.
Amazon SNS
The Amazon SNS component (aws.greengrass.SNS) publishes messages to an Amazon Simple
Notification Service (Amazon SNS) topic. You can use this component to send events from Greengrass
core devices to web servers, email addresses, and other message subscribers. For more information, see
What is Amazon SNS? in the Amazon Simple Notification Service Developer Guide.
To publish to an Amazon SNS topic with this component, publish a message to the topic where this
component subscribes. By default, this component subscribes to the sns/message local publish/
subscribe (p. 561) topic. You can specify other topics, including AWS IoT Core MQTT topics, when you
deploy this component.
In your custom component, you might want to implement filtering or formatting logic to process
messages from other sources before you publish them to this component. This enables you to centralize
your message processing logic on a single component.
Note
This component provides similar functionality to the Amazon SNS connector in AWS IoT
Greengrass V1. For more information, see Amazon SNS connector in the AWS IoT Greengrass V1
Developer Guide.
Topics
• Versions (p. 389)
• Type (p. 389)
• Operating system (p. 390)
• Requirements (p. 390)
• Dependencies (p. 391)
• Configuration (p. 393)
• Input data (p. 395)
• Output data (p. 396)
• Local log file (p. 397)
• Licenses (p. 397)
• Changelog (p. 397)
Versions
This component has the following versions:
• 2.0.x
Type
This component is a Lambda component (aws.greengrass.lambda). The Greengrass nucleus (p. 181)
runs this component's Lambda function using the Lambda launcher component (p. 252).
For more information, see Component types (p. 441).
389
AWS IoT Greengrass Developer Guide, Version 2
Operating system
Operating system
This component can be installed on Linux core devices only.
Requirements
This component has the following requirements:
• Your core device must meet the requirements to run Lambda functions. If you want the core device
to run containerized Lambda functions, the device must meet the requirements to do so. For more
information, see Lambda function requirements (p. 64).
• Python version 3.7 installed on the core device and added to the PATH environment variable.
• An Amazon SNS topic. For more information, see Creating an Amazon SNS topic in the Amazon Simple
Notification Service Developer Guide.
• The Greengrass device role (p. 790) must allow the sns:Publish action, as shown in the following
example IAM policy.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"sns:Publish"
],
"Effect": "Allow",
"Resource": [
"arn:aws:sns:region:account-id:topic-name"
]
}
]
}
You can dynamically override the default topic in the input message payload for this component. If
your application uses this feature, the IAM policy must include all target topics as resources. You can
grant granular or conditional access to resources (for example, by using a wildcard * naming scheme).
• To receive output data from this component, you must merge the following configuration update for
the legacy subscription router component (p. 260) when you deploy this component. The legacy
subscription router component (aws.greengrass.LegacySubscriptionRouter) is a dependency
of this component. This configuration specifies the topic where this component publishes responses.
Legacy subscription router v2.1.x
{
"subscriptions": {
"aws-greengrass-sns": {
"id": "aws-greengrass-sns",
"source": "component:aws.greengrass.SNS",
"subject": "sns/message/status",
"target": "cloud"
}
}
}
Legacy subscription router v2.0.x
{
"subscriptions": {
390
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
"aws-greengrass-sns": {
"id": "aws-greengrass-sns",
"source": "arn:aws:lambda:region:aws:function:aws-greengrass-sns:version",
"subject": "sns/message/status",
"target": "cloud"
}
}
}
• Replace region with the AWS Region that you use.
• Replace version with the version of the Lambda function that this component runs. To find
the Lambda function version, you must view the recipe for the version of this component that
you want to deploy. Open this component's details page in the AWS IoT Greengrass console, and
look for the Lambda function key-value pair. This key-value pair contains the name and version
of the Lambda function.
Important
You must update the Lambda function version on the legacy subscription router every
time you deploy this component. This ensures that you use the correct Lambda function
version for the component version that you deploy.
For more information, see Create deployments (p. 493).
Endpoints and ports
This component must be able to perform outbound requests to the following endpoints and ports, in
addition to endpoints and ports required for basic operation. For more information, see Allow device
traffic through a proxy or firewall (p. 807).
Endpoint Port Required Description
sns.region.amazonaws.com 443 Yes Publish
messages
to Amazon
SNS.
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 397) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.0.8
The following table lists the dependencies for version 2.0.8 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.6.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
391
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
Dependency Compatible versions Dependency type
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.7
The following table lists the dependencies for version 2.0.7 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.6
The following table lists the dependencies for version 2.0.6 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.5
The following table lists the dependencies for version 2.0.5 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.4
The following table lists the dependencies for version 2.0.4 of this component.
392
AWS IoT Greengrass Developer Guide, Version 2
Configuration
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.2.0 Hard
Lambda launcher (p. 252) ^2.0.0 Hard
Lambda runtimes (p. 258) ^2.0.0 Soft
Token exchange ^2.0.0 Hard
service (p. 407)
2.0.3
The following table lists the dependencies for version 2.0.3 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.3 <2.1.0 Hard
Lambda launcher (p. 252) >=1.0.0 Hard
Lambda runtimes (p. 258) >=1.0.0 Soft
Token exchange >=1.0.0 Hard
service (p. 407)
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
Note
This component's default configuration includes Lambda function parameters. We recommend
that you edit only the following parameters to configure this component on your devices.
lambdaParams
An object that contains the parameters for this component's Lambda function. This object contains
the following information:
EnvironmentVariables
An object that contains the Lambda function's parameters. This object contains the following
information:
DEFAULT_SNS_ARN
The ARN of the default Amazon SNS topic where this component publishes messages. You
can override the destination topic with the sns_topic_arn property in the input message
payload.
containerMode
(Optional) The containerization mode for this component. Choose from the following options:
• NoContainer – The component doesn't run in an isolated runtime environment.
393
AWS IoT Greengrass Developer Guide, Version 2
Configuration
• GreengrassContainer – The component runs in an isolated runtime environment inside the
AWS IoT Greengrass container.
Default: GreengrassContainer
containerParams
(Optional) An object that contains the container parameters for this component. The component
uses these parameters if you specify GreengrassContainer for containerMode.
This object contains the following information:
memorySize
(Optional) The amount of memory (in kilobytes) to allocate to the component.
Defaults to 512 MB (525,312 KB).
pubsubTopics
(Optional) An object that contains the topics where the component subscribes to receive messages.
You can specify each topic and whether the component subscribes to MQTT topics from AWS IoT
Core or local publish/subscribe topics.
This object contains the following information:
0 – This is an array index as a string.
An object that contains the following information:
type
(Optional) The type of publish/subscribe messaging that this component uses to subscribe
to messages. Choose from the following options:
• Pubsub – Subscribe to local publish/subscribe messages. If you choose this option, the
topic can't contain MQTT wildcards. For more information about how to send messages
from custom component when you specify this option, see Publish/subscribe local
messages (p. 561).
• IotCore – Subscribe to AWS IoT Core MQTT messages. If you choose this option, the
topic can contain MQTT wildcards. For more information about how to send messages
from custom components when you specify this option, see Publish/subscribe AWS IoT
Core MQTT messages (p. 586).
Default: Pubsub
topic
(Optional) The topic to which the component subscribes to receive messages. If you specify
IotCore for type, you can use MQTT wildcards (+ and #) in this topic.
Example Example: Configuration merge update (container mode)
{
"lambdaExecutionParameters": {
"EnvironmentVariables": {
"DEFAULT_SNS_ARN": "arn:aws:sns:us-west-2:123456789012:mytopic"
}
},
"containerMode": "GreengrassContainer"
}
394
AWS IoT Greengrass Developer Guide, Version 2
Input data
Example Example: Configuration merge update (no container mode)
{
"lambdaExecutionParameters": {
"EnvironmentVariables": {
"DEFAULT_SNS_ARN": "arn:aws:sns:us-west-2:123456789012:mytopic"
}
},
"containerMode": "NoContainer"
}
Input data
This component accepts messages on the following topic and publishes the message as is to the target
Amazon SNS topic. By default, this component subscribes to local publish/subscribe messages. For more
information about how to publish messages to this component from your custom components, see
Publish/subscribe local messages (p. 561).
Default topic (local publish/subscribe): sns/message
The message accepts the following properties. Input messages must be in JSON format.
request
The information about the message to send to the Amazon SNS topic.
Type: object that contains the following information:
message
The content of the message as a string.
To send a JSON object, serialize it as a string, and specify json for the message_structure
property.
Type: string
subject
(Optional) The subject of the message.
Type: string
The subject can be ASCII text and up to 100 characters. It must begin with a letter, number, or
punctuation mark. It can't include line breaks or control characters.
sns_topic_arn
(Optional) The ARN of the Amazon SNS topic where this component publishes the message.
Specify this property to override the default Amazon SNS topic.
Type: string
message_structure
(Optional) The structure of the message. Specify json to send a JSON message that you
serialize as a string in the content property.
Type: string
Valid values: json
395
AWS IoT Greengrass Developer Guide, Version 2
Output data
id
An arbitrary ID for the request. Use this property to map an input request to an output response.
When you specify this property, the component sets the id property in the response object to this
value.
Type: string
Note
The message size can be a maximum of 256 KB.
Example Example input: String message
{
"request": {
"subject": "Message subject",
"message": "Message data",
"sns_topic_arn": "arn:aws:sns:region:account-id:topic2-name"
},
"id": "request123"
}
Example Example input: JSON message
{
"request": {
"subject": "Message subject",
"message": "{ \"default\": \"Message data\" }",
"message_structure": "json"
},
"id": "request123"
}
Output data
This component publishes responses as output data on the following MQTT topic by default. You
must specify this topic as the subject in the configuration for the legacy subscription router
component (p. 260). For more information about how to subscribe to messages on this topic in your
custom components, see Publish/subscribe AWS IoT Core MQTT messages (p. 586).
Default topic (AWS IoT Core MQTT): sns/message/status
Example Example output: Success
{
"response": {
"sns_message_id": "f80a81bc-f44c-56f2-a0f0-d5af6a727c8a",
"status": "success"
},
"id": "request123"
}
Example Example output: Failure
{
"response" : {
"error": "InvalidInputException",
396
AWS IoT Greengrass Developer Guide, Version 2
Local log file
"error_message": "SNS Topic Arn is invalid",
"status": "fail"
},
"id": "request123"
}
Local log file
This component uses the following log file.
/greengrass/v2/logs/aws.greengrass.SNS.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 with the path to the AWS IoT Greengrass root folder.
sudo tail -f /greengrass/v2/logs/greengrass.log
Licenses
This component includes the following third-party software/licensing:
• AWS SDK for Python (Boto3)/Apache License 2.0
• botocore/Apache License 2.0
• dateutil/PSF License
• docutils/BSD License, GNU General Public License (GPL), Python Software Foundation License, Public
Domain
• jmespath/MIT License
• s3transfer/Apache License 2.0
• urllib3/MIT License
This component is released under the Greengrass Core Software License Agreement.
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.0.8 Version updated for Greengrass nucleus version 2.5.0 release.
2.0.7 Version updated for Greengrass nucleus version 2.4.0 release.
2.0.6 Version updated for Greengrass nucleus version 2.3.0 release.
2.0.5 Version updated for Greengrass nucleus version 2.2.0 release.
2.0.4 Version updated for Greengrass nucleus version 2.1.0 release.
2.0.3 Initial version.
397
AWS IoT Greengrass Developer Guide, Version 2
Stream manager
Stream manager
The stream manager component (aws.greengrass.StreamManager) enables you to process data
streams to transfer to the AWS Cloud from Greengrass core devices.
For more information about how to configure and use stream manager in custom components, see
Manage data streams on the AWS IoT Greengrass Core (p. 682).
Topics
• Versions (p. 398)
• Type (p. 398)
• Operating system (p. 398)
• Requirements (p. 398)
• Dependencies (p. 399)
• Configuration (p. 401)
• Local log file (p. 402)
• Changelog (p. 403)
Versions
This component has the following versions:
• 2.0.x
Note
If you use stream manager to export data to the cloud, you can't upgrade version 2.0.7 of the
stream manager component to a version between v2.0.8 and v2.0.11. If you are deploying
stream manager for the first time, we strongly recommend that you deploy the latest version of
the stream manager component.
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
Requirements
This component has the following requirements:
• The Authorize core devices to interact with AWS services (p. 790) must allow access to the AWS Cloud
destinations that you use with stream manager. For more information, see:
• the section called “AWS IoT Analytics channels” (p. 711)
398
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
• the section called “Amazon Kinesis data streams” (p. 712)
• the section called “AWS IoT SiteWise asset properties” (p. 713)
• the section called “Amazon S3 objects” (p. 715)
Endpoints and ports
This component must be able to perform outbound requests to the following endpoints and ports, in
addition to endpoints and ports required for basic operation. For more information, see Allow device
traffic through a proxy or firewall (p. 807).
Endpoint Port Required Description
iotanalytics.region.amazonaws.com 443 No Required if
you publish
data to
AWS IoT
Analytics.
kinesis.region.amazonaws.com 443 No Required if
you publish
data to
Kinesis Data
Firehose.
443
data.iotsitewise.region.amazonaws.com No Required if
you publish
data to AWS
IoT SiteWise.
*.s3.amazonaws.com 443 No Required if
you publish
data to S3
buckets.
You can
replace *
with the
name of
each bucket
where you
publish data.
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 403) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
2.0.13
The following table lists the dependencies for version 2.0.13 of this component.
399
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.6.0 Soft
Token exchange >=0.0.0 Hard
service (p. 407)
2.0.11 and 2.0.12
The following table lists the dependencies for versions 2.0.11 and 2.0.12 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.5.0 Soft
Token exchange >=0.0.0 Hard
service (p. 407)
2.0.10
The following table lists the dependencies for version 2.0.10 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.4.0 Soft
Token exchange >=0.0.0 Hard
service (p. 407)
2.0.9
The following table lists the dependencies for version 2.0.9 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.3.0 Soft
Token exchange >=0.0.0 Hard
service (p. 407)
2.0.8
The following table lists the dependencies for version 2.0.8 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.0 <2.2.0 Soft
Token exchange >=0.0.0 Hard
service (p. 407)
400
AWS IoT Greengrass Developer Guide, Version 2
Configuration
2.0.7
The following table lists the dependencies for version 2.0.7 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.0.3 <2.1.0 Soft
Token exchange >=0.0.0 Hard
service (p. 407)
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
STREAM_MANAGER_STORE_ROOT_DIR
(Optional) The absolute path of the local directory used to store streams. This value must start with
a forward slash (for example, /data).
STREAM_MANAGER_SERVER_PORT
(Optional) The local port number to use to communicate with stream manager.
You can specify 0 to use a random available port.
Default: 8088
STREAM_MANAGER_AUTHENTICATE_CLIENT
(Optional) You can make it mandatory for clients to authenticate before they can interact with
stream manager. The AWS IoT Greengrass Core SDK controls interaction between clients and stream
manager. This parameter determines which clients can call the AWS IoT Greengrass Core SDK to
work with streams. For more information, see stream manager client authentication (p. 684).
If you specify true, the AWS IoT Greengrass Core SDK allows only Greengrass components as
clients.
If you specify false, the AWS IoT Greengrass Core SDK allows all processes on the core device to be
clients.
Default: true
STREAM_MANAGER_EXPORTER_MAX_BANDWIDTH
(Optional) The average maximum bandwidth (in kilobits per second) that stream manager can use to
export data.
Default: No limit
STREAM_MANAGER_THREAD_POOL_SIZE
(Optional) The maximum number of active threads that stream manager can use to export data.
The optimal size depends on your hardware, stream volume, and planned number of export streams.
If your export speed is slow, you can adjust this setting to find the optimal size for your hardware
and business case. The CPU and memory of your core device hardware are limiting factors. To start,
you might try setting this value equal to the number of processor cores on the device.
401
AWS IoT Greengrass Developer Guide, Version 2
Local log file
Be careful not to set a size that's higher than your hardware can support. Each stream consumes
hardware resources, so try to limit the number of export streams on constrained devices.
Default: 5 threads
STREAM_MANAGER_EXPORTER_S3_DESTINATION_MULTIPART_UPLOAD_MIN_PART_SIZE_BYTES
(Optional) The minimum size (in bytes) of a part in a multipart upload to Amazon S3. Stream
manager uses this setting and the size of the input file to determine how to batch data in a
multipart PUT request.
Note
Stream manager uses the streams sizeThresholdForMultipartUploadBytes property
to determine whether to export to Amazon S3 as a single or multipart upload. AWS IoT
Greengrass components can set this threshold when they create a stream that exports to
Amazon S3.
Default: 5242880 (5 MB). This is also the minimum value.
JVM_ARGS
(Optional) The custom Java Virtual Machine arguments to pass to stream manager at startup.
Separate multiple arguments by spaces.
Use this parameter only when you must override the default settings used by the JVM. For example,
you might need to increase the default heap size if you plan to export a large number of streams.
Example Example: Configuration merge update
The following example configuration specifies to use a non-default port.
{
"STREAM_MANAGER_SERVER_PORT": "18088"
}
Local log file
This component uses the following log file.
Linux
/greengrass/v2/logs/aws.greengrass.StreamManager.log
Windows
C:\greengrass\v2\logs\aws.greengrass.StreamManager.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
Linux
sudo tail -f /greengrass/v2/logs/aws.greengrass.StreamManager.log
402
AWS IoT Greengrass Developer Guide, Version 2
Changelog
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\aws.greengrass.StreamManager.log -Tail 10 -Wait
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.0.13 Version updated for Greengrass nucleus version 2.5.0 release.
2.0.12 Bug fixes and improvements
Fixed an issue that prevented upgrading stream manager v2.0.7 to a version
between v2.0.8 and v2.0.11. If you use stream manager to export data to the
cloud, you can now upgrade to v2.0.12.
2.0.11 Version updated for Greengrass nucleus version 2.4.0 release.
2.0.10 Version updated for Greengrass nucleus version 2.3.0 release.
2.0.9 Version updated for Greengrass nucleus version 2.2.0 release.
2.0.8 Version updated for Greengrass nucleus version 2.1.0 release.
2.0.7 Initial version.
Systems Manager Agent
The AWS Systems Manager Agent component (aws.greengrass.SystemsManagerAgent) installs the
Systems Manager Agent, so you can manage core devices with Systems Manager. Systems Manager is
an AWS service that you can use to view and control your infrastructure on AWS, including Amazon EC2
instances, on-premises servers and virtual machines (VMs), and edge devices. Systems Manager enables
you to view operational data, automate operation tasks, and maintain security and compliance. For more
information, see What is AWS Systems Manager? and About Systems Manager Agent in the AWS Systems
Manager User Guide.
Systems Manager tools and features are called capabilities. Greengrass core devices support all Systems
Manager capabilities. For more information about these capabilities and how to use Systems Manager to
manage core devices, see Systems Manager capabilities in the AWS Systems Manager User Guide.
Topics
• Versions (p. 404)
• Type (p. 404)
• Operating system (p. 404)
• Requirements (p. 404)
• Dependencies (p. 405)
• Configuration (p. 406)
• Local log file (p. 407)
• See also (p. 407)
403
AWS IoT Greengrass Developer Guide, Version 2
Versions
• Changelog (p. 407)
Versions
This component has the following versions:
• 1.0.x
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
Operating system
This component can be installed on Linux core devices only.
Requirements
This component has the following requirements:
• A Greengrass core device that runs on a 64-bit Linux platform: Armv8 (AArch64) or x86_64.
• You must have an AWS Identity and Access Management (IAM) service role that Systems Manager can
assume. This role must include the AmazonSSMManagedInstanceCore managed policy or a custom
policy that defines equivalent permissions. For more information, see Create an IAM service role for
edge devices in the AWS Systems Manager User Guide.
When you deploy this component, you must specify this role's name for the SSMRegistrationRole
configuration parameter.
• The Greengrass device role (p. 790) must allow the ssm:AddTagsToResource and
ssm:RegisterManagedInstance actions. The device role must also allow the iam:PassRole
action for the IAM service role that fulfills the previous requirement. The following example IAM policy
grants these permissions.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"iam:PassRole"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iam::account-id:role/SSMServiceRole"
]
},
{
"Action": [
"ssm:AddTagsToResource",
"ssm:RegisterManagedInstance"
],
"Effect": "Allow",
"Resource": "*"
}
404
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
]
}
Endpoints and ports
This component must be able to perform outbound requests to the following endpoints and ports, in
addition to endpoints and ports required for basic operation. For more information, see Allow device
traffic through a proxy or firewall (p. 807).
Endpoint Port Required Description
ec2messages.region.amazonaws.com 443 Yes Communicate
with the
Systems
Manager
service in
the AWS
Cloud.
ssm.region.amazonaws.com 443 Yes Register the
core device
as a Systems
Manager
managed
node.
ssmmessages.region.amazonaws.com 443 Yes Communicate
with Session
Manager, a
capability
of Systems
Manager,
in the AWS
Cloud.
For more information, see Reference: ec2messages, ssmmessages, and other API calls in the AWS Systems
Manager User Guide.
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 407) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
The following table lists the dependencies for version 1.0.0 of this component.
Dependency Compatible versions Dependency type
Token exchange ^2.0.0 Soft
service (p. 407)
405
AWS IoT Greengrass Developer Guide, Version 2
Configuration
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
SSMRegistrationRole
The IAM service role that Systems Manager can assume and that includes the
AmazonSSMManagedInstanceCore managed policy or a custom policy that defines equivalent
permissions. For more information, see Create an IAM service role for edge devices in the AWS
Systems Manager User Guide.
SSMOverrideRegistration
(Optional) If the core device runs the Systems Manager Agent not as a Greengrass component, you
can override the device's existing Systems Manager Agent registration. Set this option to true to
register the core device as a managed node using the Systems Manager Agent that this component
provides.
Default: false
SSMResourceTags
(Optional) The tags to add to the Systems Manager managed node that this component creates for
the core device. You can use these tags to manage groups of core devices with Systems Manager. For
example, you can run a command on all devices that have a tag that you specify.
Specify a list where each tag is an object with a Key and a Value. For example, the following value
for SSMResourceTags instructs this component to set the Owner tag to richard-roe on the core
device's managed node.
[
{
"Key": "Owner",
"Value": "richard-roe"
}
]
This component ignores these tags if the managed node already exists and
SSMOverrideRegistration is false.
Example Example: Configuration merge update
The following example configuration specifies to use a service role named SSMServiceRole to allow
the core device to register and communicate with Systems Manager.
{
"SSMRegistrationRole": "SSMServiceRole",
"SSMOverrideRegistration": false,
"SSMResourceTags": [
{
"Key": "Owner",
"Value": "richard-roe"
},
{
"Key": "Team",
"Value": "solar"
406
AWS IoT Greengrass Developer Guide, Version 2
Local log file
}
]
}
Local log file
The Systems Manager Agent software writes logs to a folder outside the Greengrass root folder. For
more information, see Viewing Systems Manager Agent logs in the AWS Systems Manager User Guide.
The Systems Manager Agent component uses shell scripts to install, start, and stop the Systems Manager
Agent. You can find the output from these scripts in the following log file.
/greengrass/v2/logs/aws.greengrass.SystemsManagerAgent.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 with the path to the AWS IoT Greengrass root folder.
sudo tail -f /greengrass/v2/logs/aws.greengrass.SystemsManagerAgent.log
See also
• Manage Greengrass core devices with AWS Systems Manager (p. 761)
• What is AWS Systems Manager? in the AWS Systems Manager User Guide
• About Systems Manager Agent in the AWS Systems Manager User Guide
Changelog
The following table describes the changes in each version of the component.
Version Changes
1.0.0 Initial version.
Token exchange service
The token exchange service component (aws.greengrass.TokenExchangeService) provides AWS
credentials that you can use to interact with AWS services in your custom components.
The token exchange service runs an Amazon Elastic Container Service (Amazon ECS) container instance
as a local server. This local server connects to the AWS IoT credentials provider using the AWS IoT role
alias that you configure in the Greengrass core nucleus component (p. 181). The component provides
an environment variable, AWS_CONTAINER_CREDENTIALS_FULL_URI, that defines the URI to this
local server. When a component creates an AWS SDK client, the client recognizes this URI environment
variable to connect to the token exchange service and retrieve AWS credentials. This allows Greengrass
core devices to call AWS service operations. For more information about how to use this component in
custom components, see Interact with AWS services (p. 454).
407
AWS IoT Greengrass Developer Guide, Version 2
Versions
Important
Support to acquire AWS credentials in this way was added to the AWS SDKs on July 13th, 2016.
Your component must use an AWS SDK version that was created on or after that date. For more
information, see Using a supported AWS SDK in the Amazon Elastic Container Service Developer
Guide.
Topics
• Versions (p. 408)
• Type (p. 408)
• Operating system (p. 408)
• Dependencies (p. 408)
• Configuration (p. 408)
• Local log file (p. 408)
• Changelog (p. 409)
Versions
This component has the following versions:
• 2.0.x
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
Operating system
This component can be installed on core devices that run the following operating systems:
• Linux
• Windows
Dependencies
This component doesn't have any dependencies.
Configuration
This component doesn't have any configuration parameters.
Local log file
This component uses the same log file as the Greengrass nucleus (p. 181) component.
Linux
/greengrass/v2/logs/greengrass.log
408
AWS IoT Greengrass Developer Guide, Version 2
Changelog
Windows
C:\greengrass\v2\logs\greengrass.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root
folder.
Linux
sudo tail -f /greengrass/v2/logs/greengrass.log
Windows (PowerShell)
Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.0.3 Initial version.
IoT SiteWise OPC-UA collector
The IoT SiteWise OPC-UA collector component (aws.iot.SiteWiseEdgeCollectorOpcua) enables
AWS IoT SiteWise gateways to collect data from local OPC-UA servers.
With this component, AWS IoT SiteWise gateways can connect to multiple OPC-UA servers. For more
information about AWS IoT SiteWise gateways, see Using AWS IoT SiteWise at the edge in the AWS IoT
SiteWise User Guide.
Topics
• Versions (p. 410)
• Type (p. 410)
• Operating system (p. 410)
• Requirements (p. 410)
• Dependencies (p. 410)
• Configuration (p. 411)
• Output data (p. 411)
• Local log file (p. 411)
• Licenses (p. 411)
• Changelog (p. 411)
• See also (p. 411)
409
AWS IoT Greengrass Developer Guide, Version 2
Versions
Versions
This component has the following versions:
• 2.0.x
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
Operating system
This component can be installed on Linux core devices only.
Requirements
This component has the following requirements:
• The Greengrass core device must run on one of the following platforms:
• OS: Ubuntu 20.04 or 18.04
Architecture: x86_64 (AMD64)
• OS: Red Hat Enterprise Linux (RHEL) 8
Architecture: x86_64 (AMD64)
• OS: Amazon Linux 2
Architecture: x86_64 (AMD64)
• The Greengrass core device must allow outbound network connectivity to OPC-UA servers.
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 411) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
The following table lists the dependencies for version 2.0.x of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.3.0 <3.0.0 Hard
Stream manager (p. 398) >2.0.10<3.0.0 Hard
Secret manager (p. 374) >=2.0.8 <3.0.0 Hard
410
AWS IoT Greengrass Developer Guide, Version 2
Configuration
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component doesn't have any configuration parameters.
Output data
This component writes BatchPutAssetPropertyValue messages to AWS IoT Greengrass stream
manager. For more information, see BatchPutAssetPropertyValue in the AWS IoT SiteWise API Reference.
Local log file
This component uses the following log file.
/greengrass/v2/logs/aws.iot.SiteWiseEdgeCollectorOpcua.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 with the path to the AWS IoT Greengrass root folder.
sudo tail -f /greengrass/v2/logs/greengrass.log
Licenses
This component is released under the Greengrass Core Software License Agreement.
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.0.2 Bug fixes and improvements to asset priority syncing with edge.
2.0.1 Initial version.
See also
• What is AWS IoT SiteWise? in the AWS IoT SiteWise User Guide.
IoT SiteWise publisher
The IoT SiteWise publisher component (aws.iot.SiteWiseEdgePublisher) enables AWS IoT
SiteWise gateways to export data from the edge to the AWS Cloud.
411
AWS IoT Greengrass Developer Guide, Version 2
Versions
For more information about AWS IoT SiteWise gateways, see Using AWS IoT SiteWise at the edge in the
AWS IoT SiteWise User Guide.
Topics
• Versions (p. 412)
• Type (p. 412)
• Operating system (p. 412)
• Requirements (p. 412)
• Dependencies (p. 413)
• Configuration (p. 413)
• Input data (p. 413)
• Local log file (p. 414)
• Licenses (p. 414)
• Changelog (p. 414)
• See also (p. 414)
Versions
This component has the following versions:
• 2.0.x
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
Operating system
This component can be installed on Linux core devices only.
Requirements
This component has the following requirements:
• The Greengrass core device must run on one of the following platforms:
• OS: Ubuntu 20.04 or 18.04
Architecture: x86_64 (AMD64)
• OS: Red Hat Enterprise Linux (RHEL) 8
Architecture: x86_64 (AMD64)
• OS: Amazon Linux 2
Architecture: x86_64 (AMD64)
• The Greengrass core device must connect to the Internet.
• The Greengrass core device must be authorized to perform the
iotsitewise:BatchPutAssetPropertyValue action. For more information, see Authorize core
devices to interact with AWS services.
412
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
Example permissions policy
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*"
}
]
}
Endpoints and ports
This component must be able to perform outbound requests to the following endpoints and ports, in
addition to endpoints and ports required for basic operation. For more information, see Allow device
traffic through a proxy or firewall (p. 807).
Endpoint Port Required Description
443
data.iotsitewise.region.amazonaws.com Yes Publish data
to AWS IoT
SiteWise.
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
versions (p. 414) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
The following table lists the dependencies for version 2.0.1 of this component.
Dependency Compatible versions Dependency type
Greengrass nucleus (p. 181) >=2.3.0<3.0.0 Hard
Stream manager (p. 398) >=2.0.10<3.0.0 Hard
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component provides the following configuration parameters that you can customize when you
deploy the component.
Input data
413
AWS IoT Greengrass Developer Guide, Version 2
Local log file
This component reads BatchPutAssetPropertyValue messages from AWS IoT Greengrass stream
manager. For more information, see BatchPutAssetPropertyValue in the AWS IoT SiteWise API Reference.
Local log file
This component uses the following log file.
/greengrass/v2/logs/aws.iot.SiteWiseEdgePublisher.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 with the path to the AWS IoT Greengrass root folder.
sudo tail -f /greengrass/v2/logs/greengrass.log
Licenses
This component is released under the Greengrass Core Software License Agreement.
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.0.1 Initial version.
See also
• What is AWS IoT SiteWise? in the AWS IoT SiteWise User Guide.
IoT SiteWise processor
The IoT SiteWise processor component (aws.iot.SiteWiseEdgeProcessor) enables AWS IoT
SiteWise gateways to process data at the edge.
With this component, AWS IoT SiteWise gateways can use asset models and assets to process data on
gateway devices. For more information about AWS IoT SiteWise gateways, see Using AWS IoT SiteWise at
the edge in the AWS IoT SiteWise User Guide.
Topics
• Versions (p. 415)
• Type (p. 415)
• Operating system (p. 415)
• Requirements (p. 415)
• Dependencies (p. 416)
• Configuration (p. 417)
414
AWS IoT Greengrass Developer Guide, Version 2
Versions
• Local log file (p. 417)
• Licenses (p. 417)
• Changelog (p. 418)
• See also (p. 418)
Versions
This component has the following versions:
• 2.0.x
Type
This component is a generic component (aws.greengrass.generic). The Greengrass
nucleus (p. 181) runs the component's lifecycle scripts.
For more information, see Component types (p. 441).
Operating system
This component can be installed on Linux core devices only.
Requirements
This component has the following requirements:
• The Greengrass core device must run on one of the following platforms:
• OS: Ubuntu 20.04 or 18.04
Architecture: x86_64 (AMD64)
• OS: Red Hat Enterprise Linux (RHEL) 8
Architecture: x86_64 (AMD64)
• OS: Amazon Linux 2
Architecture: x86_64 (AMD64)
• The Greengrass core device must allow inbound traffic on port 443.
• The Greengrass core device must allow outbound traffic on port 443 and 8883.
• The following ports are reserved for use by AWS IoT SiteWise: 80, 443, 3001, 8000, 8081, 8082, 8084,
8085, 8445, 8086, 9000, 9500, and 11080. Using a reserved port for traffic can result in a terminated
connection.
• The Greengrass device role must have permissions that allow you to use AWS IoT SiteWise gateways on
your AWS IoT Greengrass V2 devices. For more information, see Requirements in the AWS IoT SiteWise
User Guide.
Endpoints and ports
This component must be able to perform outbound requests to the following endpoints and ports, in
addition to endpoints and ports required for basic operation. For more information, see Allow device
traffic through a proxy or firewall (p. 807).
415
AWS IoT Greengrass Developer Guide, Version 2
Dependencies
Endpoint Port Required Description
443
model.iotsitewise.region.amazonaws.com Yes Get
information
about your
AWS IoT
SiteWise
assets
and asset
models.
443
edge.iotsitewise.region.amazonaws.com Yes Get
information
about the
core device's
AWS IoT
SiteWise
gateway
configuration.
ecr.region.amazonaws.com 443 Yes Download
AWS IoT
SiteWise
Edge
gateway
Docker
images from
Amazon
Elastic
Container
Registry.
iot.region.amazonaws.com 443 Yes Get device
endpoints
for your
AWS
account.
sts.region.amazonaws.com 443 Yes Get the ID
of your AWS
account.
443
monitor.iotsitewise.region.amazonaws.com No Required if
you access
AWS IoT
SiteWise
Monitor
portals on
the core
device.
Dependencies
When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its
dependencies. This means that you must meet the requirements for the component and all of its
dependencies to successfully deploy the component. This section lists the dependencies for the released
416
AWS IoT Greengrass Developer Guide, Version 2
Configuration
versions (p. 418) of this component and the semantic version constraints that define the component
versions for each dependency. You can also view the dependencies for each version of the component in
the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.
The following table lists the dependencies for versions 2.0.x of this component.
Dependency Compatible versions Dependency type
Token exchange >=2.0.3 <3.0.0 Hard
service (p. 407)
Stream manager (p. 398) >=2.0.10 <3.0.0 Hard
Greengrass CLI (p. 225) >=2.3.0 <3.0.0 Hard
For more information about component dependencies, see the component recipe reference (p. 473).
Configuration
This component doesn't have any configuration parameters.
Local log file
This component uses the following log file.
/greengrass/v2/logs/aws.iot.SiteWiseEdgeProcessor.log
To view this component's logs
• Run the following command on the core device to view this component's log file in real time.
Replace /greengrass/v2 with the path to the AWS IoT Greengrass root folder.
sudo tail -f /greengrass/v2/logs/greengrass.log
Licenses
This component includes the following third-party software/licensing:
• Apache-2.0
• MIT
• BSD-2-Clause
• BSD-3-Clause
• CDDL-1.0
• CDDL-1.1
• ISC
• Zlib
• GPL-3.0-with-GCC-exception
• Public Domain
• Python-2.0
• Unicode-DFS-2015
417
AWS IoT Greengrass Developer Guide, Version 2
Changelog
• BSD-1-Clause
• OpenSSL
• EPL-1.0
• EPL-2.0
• GPL-2.0-with-classpath-exception
• MPL-2.0
• CC0-1.0
• JSON
This component is released under the Greengrass Core Software License Agreement.
Changelog
The following table describes the changes in each version of the component.
Version Changes
2.0.2 Initial version.
See also
• What is AWS IoT SiteWise? in the AWS IoT SiteWise User Guide.
418
AWS IoT Greengrass Developer Guide, Version 2
Community components
The Greengrass Software Catalog is an index of Greengrass components that are developed by the
Greengrass community. From this catalog, you can download, modify, and deploy components to create
your Greengrass applications. You can view the catalog at the following link: https://github.com/aws-
greengrass/aws-greengrass-software-catalog.
Each component has a public GitHub repository that you can explore. View the Greengrass Software
Catalog on GitHub to find the full list of community components. For example, this catalog includes the
following components:
• InfluxDB
This component provides an InfluxDB time-series database on a Greengrass core device. You can use
this component to process data from IoT sensors, analyze data in real time, and monitor operations at
the edge.
• Local Grafana server
This component enables you to host a Grafana server on a Greengrass core device. You can use
Grafana dashboards to visualize and manage data on the core device.
• Amazon Kinesis Video Streams
This component ingests audio and video streams from local cameras that use Real Time Streaming
Protocol (RTSP). The component then uploads the audio and video streams to Amazon Kinesis Video
Streams.
• Local web server
This component enables you to create a local web user interface on a Greengrass core device. You
can create a local web user interface that enables you to configure device and application settings or
monitor the device, for example.
• LoRaWaN protocol adapter
This component ingests data from local wireless devices that use the LoRaWaN protocol, which is a
Low Power Wide Area Networking (LPWAN) protocol. The component enables you to analyze and act
on data locally without communicating with the cloud.
To request feature or report a bug, open a GitHub issue on the repository for that component. AWS
doesn't provide support for community components. For more information, see the CONTRIBUTING.md
file in each component's repository.
Several AWS-provided components are also open source. For more information, see Open source AWS
IoT Greengrass Core software (p. 921).
419
AWS IoT Greengrass Developer Guide, Version 2
Greengrass Development Kit CLI
AWS IoT Greengrass development
tools
Use AWS IoT Greengrass development tools to create, test, build, publish, and deploy custom Greengrass
components.
• Greengrass Development Kit CLI (p. 420)
Use the AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) in your local
development environment to create components from templates and community components in the
Greengrass Software Catalog (p. 419). You can use the GDK CLI to build the component and publish
the component to the AWS IoT Greengrass service as a private component in your AWS account.
• Greengrass Command Line Interface (p. 428)
Use the Greengrass Command Line Interface (Greengrass CLI) on Greengrass core devices to deploy
and debug Greengrass components. The Greengrass CLI is a component that you can deploy to your
core devices to create local deployments, view details about installed components, and explore log
files.
• Local debug console (p. 265)
Use the local debug console on Greengrass core devices to deploy and debug Greengrass components
using a local dashboard web interface. The local debug console is a component that you can deploy to
your core devices to create local deployments and view details about installed components.
Topics
• AWS IoT Greengrass Development Kit Command-Line Interface (p. 420)
• Greengrass Command Line Interface (p. 428)
AWS IoT Greengrass Development Kit Command-
Line Interface
The AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) provides features that
help you develop custom Greengrass components (p. 440). You can use the GDK CLI to create, build,
and publish custom components. When you create a component repository with the GDK CLI, you can
start from a template or a community component from the Greengrass Software Catalog (p. 419). Then,
you can choose a build system that packages files as ZIP archives, uses a Maven or Gradle build script,
or runs a custom build command. After you create a component, you can use the GDK CLI to publish it
to the AWS IoT Greengrass service, so you can use the AWS IoT Greengrass console or API to deploy the
component to your Greengrass core devices.
When you develop Greengrass components without the GDK CLI, you must update the version
and artifact URIs in the component recipe file (p. 471) each time you create a new version of the
component. When you use the GDK CLI, it can automatically update the version and artifact URIs for you
each time you publish a new version of the component.
420
AWS IoT Greengrass Developer Guide, Version 2
Prerequisites
The GDK CLI is open source and available on GitHub. You can customize and extend the GDK CLI to meet
your component development needs. We invite you to open issues and pull requests on the GitHub
repository. You can find the GDK CLI source at the following link: https://github.com/aws-greengrass/
aws-greengrass-gdk-cli.
Prerequisites
To install and use the Greengrass Development Kit CLI, you need the following:
• An AWS account. If you don't have one, see Set up an AWS account (p. 66).
• A Windows, macOS, or Unix-like development computer with an internet connection.
• Python 3.8 or later installed on your development computer.
• AWS Command Line Interface (AWS CLI) installed and configured with credentials on your
development computer. For more information, see Installing, updating, and uninstalling the AWS CLI
and Configuring the AWS CLI in the AWS Command Line Interface User Guide.
Note
If you use a Raspberry Pi or another 32-bit ARM device, install AWS CLI V1. AWS CLI V2
isn't available for 32-bit ARM devices. For more information, see Installing, updating, and
uninstalling the AWS CLI version 1.
• To use the GDK CLI to publish components to the AWS IoT Greengrass service,
you must have the following permissions: s3:CreateBucket, s3:PutObject,
greengrass:CreateComponentVersion, greengrass:ListComponentVersions.
Install the AWS IoT Greengrass Development Kit
Command-Line Interface
The AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) is built on Python, so you
can use pip to install it on your development computer.
Tip
You can also install the GDK CLI in a Python virtual environments such as venv. For more
information, see Virtual Environments and Packages in the Python 3 documentation.
To install the GDK CLI
1. Run the following command to install the GDK CLI from its GitHub repository.
python3 -m pip install git+https://github.com/aws-greengrass/aws-greengrass-gdk-cli.git
2. Run the following command to verify that the GDK CLI installed successfully.
gdk --help
If the gdk command isn't found, add its folder to PATH.
• On Linux devices, add /home/MyUser/.local/bin to PATH.
• On Windows devices, add PythonPath\Scripts to PATH, and replace PythonPath with the
path to the Python folder on your device.
You can now use the GDK CLI to create, build, and publish Greengrass components. For more information
about how to use the GDK CLI, see AWS IoT Greengrass Development Kit Command-Line Interface
commands (p. 422).
421
AWS IoT Greengrass Developer Guide, Version 2
GDK CLI commands
AWS IoT Greengrass Development Kit Command-Line
Interface commands
The AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) provides a command line
interface that you can use to create, build, and publish Greengrass components on your development
computer. GDK CLI commands use the following format.
gdk <command> <subcommand> [arguments]
When you install the GDK CLI (p. 421), the installer adds gdk to the PATH so you can run the GDK CLI
from the command line.
You can use the following arguments with any command:
• Use -h or --help for information about a GDK CLI command.
• Use -v or --version to see what version of GDK CLI is installed.
• Use -d or --debug to output verbose logs that you can use to debug the GDK CLI.
This section describes the GDK CLI commands and provides examples for each command. The synopsis
for each command shows its arguments and their usage. Optional arguments are shown in square
brackets.
Available commands
• component (p. 422)
component
Use the component command in the AWS IoT Greengrass Development Kit Command-Line Interface
(GDK CLI) to create, build, and publish custom Greengrass components.
Subcommands
• init (p. 422)
• build (p. 423)
• publish (p. 424)
• list (p. 425)
init
Initialize a Greengrass component folder from a component template or community component.
The GDK CLI retrieves community components from the Greengrass Software Catalog (p. 419) and
component templates from the AWS IoT Greengrass Component Templates repository on GitHub.
Note
You must run the gdk component init command in an empty folder. The GDK CLI downloads
the template or community component to the current folder.
Synopsis
$ gdk component init
[--language]
[--template]
422
AWS IoT Greengrass Developer Guide, Version 2
GDK CLI commands
[--repository]
Arguments (initialize from component template)
• -l, --language – The programming language to use for the template that you specify.
• -t, --template – The component template to use for a local component project. To view
available templates, use the list (p. 425) command.
Arguments (initialize from community component)
• -r, --repository – The community component to check out into the local folder. To view
available community components, use the list (p. 425) command.
Output
The following example shows the output produced when you run this command.
$ gdk component init -l python -t HelloWorld
[2021-11-29 12:51:40] INFO - Initializing the project directory with a python component
template - 'HelloWorld'.
[2021-11-29 12:51:40] INFO - Fetching the component template 'HelloWorld-python' from
Greengrass Software Catalog.
build
Build a component's source into a recipe and artifacts that you can publish to the AWS IoT Greengrass
service. The GDK CLI runs the build system that you specify in the GDK CLI configuration file (p. 425),
gdk-config.json. You must run this command in the same folder where the gdk-config.json file
exists.
When you run this command, the GDK CLI creates a recipe and artifacts in the
greengrass-build folder in the component folder. The GDK CLI saves the recipe in the
greengrass-build/recipes folder and saves the artifacts in the greengrass-build/
artifacts/componentName/componentVersion folder.
After you build a component, you can do one of the following to test it on a Greengrass core device:
• If you develop on a different device than where you run the AWS IoT Greengrass Core software, you
must publish the component to deploy it to a Greengrass core device. Publish the component to the
AWS IoT Greengrass service, and deploy it to the Greengrass core device. For more information, see the
publish (p. 423) command and Create deployments (p. 493).
• If you develop on the same device where you run the AWS IoT Greengrass Core software, you can
publish the component to the AWS IoT Greengrass service to deploy, or you can create a local
deployment to install and run the component. To create a local deployment, use the Greengrass
CLI. For more information, see Greengrass Command Line Interface (p. 428) and Test AWS IoT
Greengrass components with local deployments (p. 449). When you create the local deployment,
specify greengrass-build/recipes as the recipes folder and greengrass-build/artifacts as
the artifacts folder.
Synopsis
$ gdk component build
Arguments
None
Output
The following example shows the output produced when you run this command.
423
AWS IoT Greengrass Developer Guide, Version 2
GDK CLI commands
$ gdk component build
[2021-11-29 13:18:49] INFO - Getting project configuration from gdk-config.json
[2021-11-29 13:18:49] INFO - Found component recipe file 'recipe.yaml' in the project
directory.
[2021-11-29 13:18:49] INFO - Building the component 'com.example.PythonHelloWorld' with
the given project configuration.
[2021-11-29 13:18:49] INFO - Using 'zip' build system to build the component.
[2021-11-29 13:18:49] WARNING - This component is identified as using 'zip' build
system. If this is incorrect, please exit and specify custom build command in the
'gdk-config.json'.
[2021-11-29 13:18:49] INFO - Zipping source code files of the component.
[2021-11-29 13:18:49] INFO - Copying over the build artifacts to the greengrass
component artifacts build folder.
[2021-11-29 13:18:49] INFO - Updating artifact URIs in the recipe.
[2021-11-29 13:18:49] INFO - Creating component recipe in 'C:\Users\MyUser\Documents
\greengrass-components\python\HelloWorld\greengrass-build\recipes'.
publish
Publish this component to the AWS IoT Greengrass service. This command uploads build artifacts to
an S3 bucket, updates the artifact URI in the recipe, and creates a new version of component from the
recipe. The GDK CLI uses the S3 bucket and AWS Region that you specify in the GDK CLI configuration
file (p. 425), gdk-config.json. You must run this command in the same folder where the gdk-
config.json file exists.
The GDK CLI uploads to the S3 bucket whose name is bucketName-region-accountId, where
bucketName and region are the values that you specify in gdk-config.json. The GDK CLI creates the
bucket if it doesn't exist.
When you run this command, the GDK CLI publishes the component with the version that you specify
in the recipe. If you specify NEXT_PATCH, the GDK CLI uses the next patch version that doesn't already
exist. Semantic versions use a major.minor.patch numbering system. For more information, see the
semantic version specification.
Synopsis
$ gdk component publish
Arguments
None
Output
The following example shows the output produced when you run this command.
$ gdk component publish
[2021-11-29 13:45:29] INFO - Getting project configuration from gdk-config.json
[2021-11-29 13:45:29] INFO - Found component recipe file 'recipe.yaml' in the project
directory.
[2021-11-29 13:45:29] INFO - Found credentials in shared credentials file: ~/.aws/
credentials
[2021-11-29 13:45:30] INFO - Publishing the component 'com.example.PythonHelloWorld'
with the given project configuration.
[2021-11-29 13:45:30] INFO - No private version of the component
'com.example.PythonHelloWorld' exist in the account. Using '1.0.0' as the next version
to create.
[2021-11-29 13:45:30] INFO - Uploading the component built artifacts to s3 bucket.
[2021-11-29 13:45:30] INFO - Uploading component artifacts to S3 bucket: {bucket}. If
this is your first time using this bucket, add the 's3:GetObject' permission to each
424
AWS IoT Greengrass Developer Guide, Version 2
GDK CLI configuration file
core device's token exchange role to allow it to download the component artifacts. For
more information, see https://docs.aws.amazon.com/greengrass/v2/developerguide/device-
service-role.html.
[2021-11-29 13:45:30] INFO - Not creating an artifacts bucket as it already exists.
[2021-11-29 13:45:30] INFO - Updating the component recipe
com.example.PythonHelloWorld-1.0.0.
[2021-11-29 13:45:30] INFO - Creating a new greengrass component
com.example.PythonHelloWorld-1.0.0
[2021-11-29 13:45:30] INFO - Created private version '1.0.0' of the component in the
account.'com.example.PythonHelloWorld'.
list
Retrieve the list of available component templates and community components.
The GDK CLI retrieves community components from the Greengrass Software Catalog (p. 419) and
component templates from the AWS IoT Greengrass Component Templates repository on GitHub.
You can pass the output of this command to the init (p. 422) command to initialize component
repositories from templates and community components.
Synopsis
$ gdk component list
[--template]
[--repository]
Arguments
• -t, --template – (Optional) Specify this argument to list available component templates. This
command outputs the name and language of each template in the format name-language.
For example, in HelloWorld-python, the template name is HelloWorld and the language is
python.
• -r, --repository – (Optional) Specify this argument to list available community component
repositories.
Output
The following example shows the output produced when you run this command.
$ gdk component list --template
[2021-11-29 12:29:04] INFO - Listing all the available component templates from
Greengrass Software Catalog.
[2021-11-29 12:29:04] INFO - Found '2' component templates to display.
1. HelloWorld-python
2. HelloWorld-java
Greengrass Development Kit CLI configuration file
The AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) reads from a configuration
file named gdk-config.json to build and publish components. This configuration file must exist in
the root of the component repository. You can use the GDK CLI init command (p. 422) to initialize
component repositories with this configuration file.
Topics
• GDK CLI configuration file format (p. 426)
• GDK CLI configuration file examples (p. 427)
425
AWS IoT Greengrass Developer Guide, Version 2
GDK CLI configuration file
GDK CLI configuration file format
When you define a GDK CLI configuration file for a component, you specify the following information in
JSON format.
gdk_version
The version of the GDK CLI that this component source folder uses. Choose from the following
options:
• 1.0.0
component
The configuration for this component.
componentName
author
The author or publisher of the component.
version
The version of the component. Specify one of the following:
• NEXT_PATCH – When you choose this option, the GDK CLI sets the version when you
publish the component. The GDK CLI queries the AWS IoT Greengrass service to identify
the latest published version of the component. Then, it sets the version to the next patch
version after that version. If you haven't published the component before, the GDK CLI
uses version 1.0.0.
If you choose this option, you can't use the Greengrass CLI (p. 225) to locally deploy
and test the component to your local development computer that runs the AWS IoT
Greengrass Core software. To enable local deployments, you must specify a semantic
version instead.
• A semantic version, such as 1.0.0. Semantic versions use a major.minor.patch numbering
system. For more information, see the semantic version specification.
If you develop components on a Greengrass core device where you want to deploy and
test the component, choose this option. You must build the component with a specific
version to create local deployments with the Greengrass CLI (p. 225)
build
The configuration to use to build this component's source into artifacts. This object contains
the following information:
build_system
The build system to use. Choose from the following options:
• zip – Packages the component's source into a ZIP file to define as the component's
only artifact. Choose this option for the following types of components:
• Components that use interpreted programming languages, such as Python or
JavaScript.
• Components that package files other than code, such as machine learning models
or other resources.
When you use the zip build system, the GDK CLI zips the contents in the
component's source folder, except the following:
• The gdk-config.json file
• The recipe file (recipe.json or recipe.yaml)
• Build folders, such as greengrass-build
426
AWS IoT Greengrass Developer Guide, Version 2
GDK CLI configuration file
• maven – Runs the mvn clean package command to build the component's source
into artifacts. Choose this option for components that use Maven, such as Java
components.
• gradle – Runs the gradle build command to build the component's source into
artifacts. Choose this option for components that use Gradle.
• custom – Runs a custom command to build the component's source into artifacts.
Specify the custom command in the custom_build_command parameter.
custom_build_command
(Optional) The custom build command to run for custom build systems. You must
specify this parameter if you specify custom for build_system. Specify single string
or a list of strings, where each string is a word in the command. For example, to run
a custom build command for a C++ component, you might specify cmake --build
build --config Release or ["cmake", "--build", "build", "--config",
"Release"].
publish
The configuration to use to publish this component to the AWS IoT Greengrass service.
The GDK CLI uploads to the S3 bucket whose name is bucketName-region-accountId,
where bucketName and region are the values that you specify in gdk-config.json. The
GDK CLI creates the bucket if it doesn't exist.
This object contains the following information:
bucket
The S3 bucket name to use to host component artifacts.
region
The AWS Region where the GDK CLI publishes this component.
GDK CLI configuration file examples
You can reference the following GDK CLI configuration file examples to help you configure Greengrass
component environments.
Hello World (Python)
The following GDK CLI configuration file supports a Hello World component that runs a Python script.
This configuration file uses the zip build system to package the component's Python script into a ZIP file
that the GDK CLI uploads as an artifact.
{
"component": {
"com.example.PythonHelloWorld": {
"author": "Amazon",
"version": "NEXT_PATCH",
"build": {
"build_system" : "zip"
},
"publish": {
"bucket": "greengrass-component-artifacts",
"region": "us-west-2"
}
}
},
"gdk_version": "1.0.0"
427
AWS IoT Greengrass Developer Guide, Version 2
Greengrass Command Line Interface
Hello World (Java)
The following GDK CLI configuration file supports a Hello World component that runs a Java application.
This configuration file uses the maven build system to package the component's Java source code into a
JAR file that the GDK CLI uploads as an artifact.
{
"component": {
"com.example.JavaHelloWorld": {
"author": "Amazon",
"version": "NEXT_PATCH",
"build": {
"build_system" : "maven"
},
"publish": {
"bucket": "greengrass-component-artifacts",
"region": "us-west-2"
}
}
},
"gdk_version": "1.0.0"
}
Greengrass Command Line Interface
The Greengrass Command Line Interface (CLI) lets you interact with AWS IoT Greengrass Core on your
device to locally develop components and debug issues. For example, you can use the Greengrass CLI to
create a local deployment and restart a component on the core device.
Deploy the Greengrass CLI component (p. 225) (aws.greengrass.Cli) to install the Greengrass CLI on
your core device.
Important
We recommend that you use this component in only development environments, not production
environments. This component provides access to information and operations that you typically
won't need in a production environment. Follow the principle of least privilege by deploying this
component to only core devices where you need it.
Topics
• Install the Greengrass CLI (p. 428)
• Greengrass CLI commands (p. 431)
Install the Greengrass CLI
You can install the Greengrass CLI in one of the following ways:
• Use the --deploy-dev-tools argument when you first set up AWS IoT Greengrass Core software on
your device. You must also specify --provision true to apply this argument.
• Deploy the Greengrass CLI component (aws.greengrass.Cli) on your device.
This section describes the steps to deploy the Greengrass CLI component. For information about
installing the Greengrass CLI during initial setup, see Getting started with AWS IoT Greengrass V2 (p. 31).
428
AWS IoT Greengrass Developer Guide, Version 2
Install the Greengrass CLI
Prerequisites
To deploy the Greengrass CLI component, you must meet the following requirements:
• AWS IoT Greengrass Core software installed and configured on your core device. For more information,
see Getting started with AWS IoT Greengrass V2 (p. 31).
• To use the AWS CLI to deploy the Greengrass CLI, you must have installed and configured the AWS CLI.
For more information, see Configuring the AWS CLI in the AWS Command Line Interface User Guide.
• You must be authorized to use the Greengrass CLI to interact with the AWS IoT Greengrass Core
software. Do one of the following to use the Greengrass CLI:
• Use the system user that runs the AWS IoT Greengrass Core software.
• Use a user with root or adminstrative permissions. On Linux core devices, you can use sudo to gain
root permissions.
• Use a system user that's in a group that you specify in the AuthorizedPosixGroups or
AuthorizedWindowsGroups configuration parameters when you deploy the component. For more
information, see Greengrass CLI component configuration (p. 228).
Deploy the Greengrass CLI component
Complete the following steps to deploy the Greengrass CLI component to your core device:
To deploy the Greengrass CLI component (console)
1. Sign in to the AWS IoT Greengrass console.
2. In the navigation menu, choose Components.
3. On the Components page, on the Public components tab, choose aws.greengrass.Cli.
4. On the aws.greengrass.Cli page, choose Deploy.
5. From Add to deployment, choose Create new deployment.
6. On the Specify target page, under Deployment targets, in the Target name list, choose the
Greengrass group that you want to deploy to, and choose Next.
7. On the Select components page, verify that the aws.greengrass.Cli component is selected, and
choose Next.
8. On the Configure components page, keep the default configuration settings, and choose Next.
9. On the Configure advanced setting page, keep the default configuration settings, and choose Next.
10. On the Review page, click Deploy
To deploy the Greengrass CLI component (AWS CLI)
1. On your device, create a deployment.json file to define the deployment configuration for the
Greengrass CLI component. This file should look like the following:
{
"targetArn":"targetArn",
"components": {
"aws.greengrass.Cli": {
"componentVersion": "2.5.2",
"configurationUpdate": {
"merge": "{\"AuthorizedPosixGroups\":\"<group1>,<group2>,...,<groupN>\",
\"AuthorizedWindowsGroups\":\"<group1>,<group2>,...,<groupN>\"}"
}
}
}
}
429
AWS IoT Greengrass Developer Guide, Version 2
Install the Greengrass CLI
• In the target field, replace targetArn with the Amazon Resource Name (ARN) of the thing or
thing group to target for the deployment, in the following format:
• Thing: arn:aws:iot:region:account-id:thing/thingName
• Thing group: arn:aws:iot:region:account-id:thinggroup/thingGroupName
• In the aws.greengrass.Cli component object, specify values as follows:
version
The version of the Greengrass CLI component.
configurationUpdate.AuthorizedPosixGroups
(Optional) A string that contains a comma-separated list of system groups. You authorize
these system groups to use the Greengrass CLI to interact with the AWS IoT Greengrass Core
software. You can specify group names or group IDs. For example, group1,1002,group3
authorizes three system groups (group1, 1002, and group3) to use the Greengrass CLI.
If you don't specify any groups to authorize, you can use the Greengrass CLI as the root user
(sudo) or as the system user that runs the AWS IoT Greengrass Core software.
configurationUpdate.AuthorizedWindowsGroups
(Optional) A string that contains a comma-separated list of system groups. You authorize
these system groups to use the Greengrass CLI to interact with the AWS IoT Greengrass Core
software. You can specify group names or group IDs. For example, group1,1002,group3
authorizes three system groups (group1, 1002, and group3) to use the Greengrass CLI.
If you don't specify any groups to authorize, you can use the Greengrass CLI as an
administrator or as the system user that runs the AWS IoT Greengrass Core software.
2. Run the following command to deploy the Greengrass CLI component on the device:
$ aws greengrassv2 create-deployment --cli-input-json file://path/to/deployment.json
During installation, the component adds a symbolic link to greengrass-cli in the /greengrass/
v2/bin folder on your device, and you run the Greengrass CLI from this path. To run the Greengrass CLI
without its absolute path, add your /greengrass/v2/bin folder to your PATH variable. To verify the
Greengrass CLI installation, run the following command:
Linux or Unix
/greengrass/v2/bin/greengrass-cli help
Windows
C:\greengrass\v2\bin\greengrass-cli help
You should see the following output:
Usage: greengrass-cli [-hV] [--ggcRootPath=<ggcRootPath>] [COMMAND]
Greengrass command line interface
--ggcRootPath=<ggcRootPath>
The AWS IoT Greengrass V2 root directory.
-h, --help Show this help message and exit.
-V, --version Print version information and exit.
Commands:
430
AWS IoT Greengrass Developer Guide, Version 2
Greengrass CLI commands
help Show help information for a command.
component Retrieve component information and stop or restart
components.
deployment Create local deployments and retrieve deployment status.
logs Analyze Greengrass logs.
get-debug-password Generate a password for use with the HTTP debug view
component.
If the greengrass-cli isn't found, the deployment might have failed to install the Greengrass CLI. For
more information, see Troubleshooting AWS IoT Greengrass V2 (p. 911).
Greengrass CLI commands
The Greengrass CLI provides a command line interface to interact locally with your AWS IoT Greengrass
core device. Greengrass CLI commands use the following format.
$ greengrass-cli <command> <subcommand> [arguments]
By default, the greengrass-cli executable file in the /greengrass/v2/bin/ folder interacts with
the version of the AWS IoT Greengrass Core software running in the /greengrass/v2 folder. If you call
an executable that is not placed in this location, or if you want to interact with AWS IoT Greengrass Core
software in a different location, then you must use one of the following methods to explicitly specify the
root path of the AWS IoT Greengrass Core software that you want to interact with:
• Set the GGC_ROOT_PATH environment variable to /greengrass/v2.
• Add the --ggcRootPath /greengrass/v2 argument to your command as shown in the following
example.
greengrass-cli --ggcRootPath /greengrass/v2 <command> <subcommand> [arguments]
You can use the following arguments with any command:
• Use --help for information about a specific Greengrass CLI command.
• Use --version for information about the Greengrass CLI version.
This section describes the Greengrass CLI commands and provides examples for these commands. The
synopsis for each command shows its arguments and their usage. Optional arguments are shown in
square brackets.
Available commands
• component (p. 431)
• deployment (p. 433)
• logs (p. 436)
• get-debug-password (p. 439)
component
Use the component command to interact with local components on your core device.
Subcommands
• details (p. 432)
431
AWS IoT Greengrass Developer Guide, Version 2
Greengrass CLI commands
• list (p. 432)
• restart (p. 433)
• stop (p. 433)
details
Retrieve the version, status, and configuration of one component.
Synopsis
greengrass-cli component details --name <component-name>
Arguments
--name, -n. The component name.
Output
The following example shows the output produced when you run this command.
$ sudo greengrass-cli component details --name MyComponent
Component Name: MyComponent
Version: 1.0.0
State: RUNNING
Configuration: null
list
Retrieve the names, component details, and runtime configuration for all root-level components.
Synopsis
greengrass-cli component list
Arguments
None
Output
The following example shows the output produced when you run this command.
$ sudo greengrass-cli component list
Components currently running in Greengrass:
Component Name: FleetStatusService
Version: 0.0.0
State: RUNNING
Configuration: {"periodicUpdateIntervalSec":86400.0}
Component Name: UpdateSystemPolicyService
Version: 0.0.0
State: RUNNING
Configuration: null
Component Name: aws.greengrass.Nucleus
Version: 2.0.0
State: FINISHED
Configuration: {"awsRegion":"region","runWithDefault":
{"posixUser":"ggc_user:ggc_group"},"telemetry":{}}
432
AWS IoT Greengrass Developer Guide, Version 2
Greengrass CLI commands
Component Name: DeploymentService
Version: 0.0.0
State: RUNNING
Configuration: null
Component Name: TelemetryAgent
Version: 0.0.0
State: RUNNING
Configuration: null
Component Name: aws.greengrass.Cli
Version: 2.0.0
State: RUNNING
Configuration: {"AuthorizedPosixGroups":"ggc_user"}
restart
Restart components.
Synopsis
greengrass-cli component restart --names <component-name>,...
Arguments
--names, -n. The component name. At least one component name is required. You can specify
additional component names, separating each name with a comma.
Output
None
stop
Stop running components.
Synopsis
greengrass-cli component stop --names <component-name>,...
Arguments
--names, -n. The component name. At least one component name is required. You can specify
additional component names if needed, separating each name with a comma.
Output
None
deployment
Use the deployment command to interact with local components on your core device.
Subcommands
• create (p. 434)
• list (p. 435)
• status (p. 436)
433
AWS IoT Greengrass Developer Guide, Version 2
Greengrass CLI commands
create
Create or update a local deployment using specified component recipes, artifacts, and runtime
arguments.
Synopsis
greengrass-cli deployment create
--recipeDir path/to/component/recipe
[--artifactDir path/to/artifact/folder ]
[--update-config {component-configuration}]
[--groupId <thing-group>]
[--merge "<component-name>=<component-version>"]...
[--runWith "<component-name>:posixUser=<user-name>[:<group-name>]"]...
[--systemLimits "{component-system-resource-limits}]"]...
[--remove <component-name>,...]
Arguments
• --recipeDir, -r. The full path to the folder that contains the component recipe files.
• --artifactDir, -a. The full path to the folder that contains the artifact files you want to
include in your deployment. The artifacts folder must contain the following directory structure:
/path/to/artifact/folder/<artifact-name>/<version>/<artifacts>
• --update-config, -c. The configuration arguments for the deployment, provided as a JSON
string or a JSON file. The JSON string should be in the following format:
{ \
"componentName": { \
"MERGE": {"config-key": "config-value"}, \
"RESET": ["path/to/reset/"] \
} \
}
MERGE and RESET are case-sensitive and must be in upper case.
• --groupId, -g. The target thing group for the deployment.
• --merge, -m. The name and version of the target component that you want to add or update.
You must provide the component information in the format <component>=<version>. Use
a separate argument for each additional component to specify. If needed, use the --runWith
argument to provide the posixUser, posixGroup, and windowsUser information for running
the component.
• --runWith. The posixUser, posixGroup, and windowsUser information for running a
generic or Lambda component. You must provide this information in the format <component>:
{posixUser|windowsUser}=<user>[:<=posixGroup>]. For example, you might specify
HelloWorld:posixUser=ggc_user:ggc_group or HelloWorld:windowsUser=ggc_user.
Use a separate argument for each additional option to specify.
For more information, see Configure the user that runs components (p. 161).
• --systemLimits. The system resource limits to apply to generic and non-containerized Lambda
components' processes on the core device. You can configure the maximum amount of CPU and
RAM usage that each component's processes can use on the core device. Specify a serialized JSON
object or a file path to a JSON file. The JSON object must have the following format.
{ \
"componentName": { \
"cpus": cpuTimeLimit, \
"memory": memoryLimitInKb \
434
AWS IoT Greengrass Developer Guide, Version 2
Greengrass CLI commands
} \
}
You can configure the following system resource limits for each component:
• cpus – The maximum amount of CPU time that this component's processes can use on the core
device. A core device's total CPU time is equivalent to the device's number of CPU cores. For
example, on a core device with 4 CPU cores, you can set this value to 2 to limit this component's
processes to 50 percent usage of each CPU core. On a device with 1 CPU core, you can set this
value to 0.25 to limit this component's processes to 25 percent usage of the CPU. If you set
this value to a number greater than the number of CPU cores, the AWS IoT Greengrass Core
software doesn't limit the component's CPU usage.
• memory – The maximum amount of RAM (in kilobytes) that this component's processes can use
on the core device.
For more information, see Configure system resource limits for components (p. 164).
This feature is available for v2.4.0 and later of the Greengrass nucleus component (p. 181) and
Greengrass CLI on Linux core devices. AWS IoT Greengrass doesn't currently support this feature
on Windows core devices.
• --remove. The name of the target component that you want to remove from a local deployment.
To remove a component that was merged from a cloud deployment, you must provide the group
ID of the target thing group in the following format:
Greengrass nucleus v2.4.0 and later
--remove <component-name> --groupId <group-name>
Earlier than v2.4.0
--remove <component-name> --groupId thinggroup/<group-name>
Output
The following example shows the output produced when you run this command.
$ sudo greengrass-cli deployment create \
--merge MyApp1=1.0.0 \
--merge MyApp2=1.0.0 --runWith MyApp2:posixUser=ggc_user \
--remove MyApp3 \
--recipeDir recipes/ \
--artifactDir artifacts/
Local deployment has been submitted! Deployment Id: 44d89f46-1a29-4044-
ad89-5151213dfcbc
list
Retrieve the status of the last 10 local deployments.
Synopsis
greengrass-cli deployment list
Arguments
None
435
AWS IoT Greengrass Developer Guide, Version 2
Greengrass CLI commands
Output
The following example shows the output produced when you run this command. Depending on the
status of your deployment, the output shows one of the following status values: IN_PROGRESS,
SUCCEEDED, or FAILED.
$ sudo greengrass-cli deployment list
44d89f46-1a29-4044-ad89-5151213dfcbc: SUCCEEDED
status
Retrieve the status of a specific deployment.
Synopsis
greengrass-cli deployment status -i <deployment-id>
Arguments
-i. The ID of the deployment.
Output
The following example shows the output produced when you run this command. Depending on the
status of your deployment, the output shows one of the following status values: IN_PROGRESS,
SUCCEEDED, or FAILED.
$ sudo greengrass-cli deployment status -i 44d89f46-1a29-4044-ad89-5151213dfcbc
44d89f46-1a29-4044-ad89-5151213dfcbc: FAILED
logs
Use the logs command to analyze Greengrass logs on your core device.
Subcommands
• get (p. 436)
• list-keywords (p. 438)
• list-log-files (p. 439)
get
Collect, filter, and visualize Greengrass log files. This command supports only JSON-formatted log files.
You can specify the logging format (p. 186) in the nucleus configuration.
Synopsis
greengrass-cli logs get
[--log-dir path/to/a/log/folder]
[--log-file path/to/a/log/file]
[--follow true | false ]
[--filter <filter> ]
436
AWS IoT Greengrass Developer Guide, Version 2
Greengrass CLI commands
[--time-window <start-time>,<end-time> ]
[--verbose ]
[--no-color ]
[--before <value> ]
[--after <value> ]
[--syslog ]
[--max-long-queue-size <value> ]
Arguments
• --log-dir, -ld. The path to the directory to check for log files, such as /greengrass/
v2/logs. Do not use with --syslog. Use a separate argument for each additional directory
to specify. You must use at least one of --log-dir or --log-file. You can also use both
arguments in a single command.
• --log-file, -lf. The paths to the log directories you want to use. Use a separate argument for
each additional directory to specify. You must use at least one of --log-dir or --log-file. You
can also use both arguments in a single command.
• --follow, -fol. Show log updates as they occur. Greengrass CLI continues to run and reads from
the specified logs. If you specify a time window, then Greengrass CLI stops monitoring logs after
all of the time windows end.
• --filter, -f. The keyword, regular expressions, or key-value pair to use as a filter. Provide this
value as a string, a regular expression, or as a key-value pair. Use a separate argument for each
additional filter to specify.
When evaluated, multiple filters specified in a single argument are separated by OR operators, and
filters specified in additional arguments are combined with AND operators. For example, if your
command includes --filter "installed" --filter "name=alpha,name=beta", then
Greengrass CLI will filter and display log messages that contain both the keyword installed and
a name key that has the values alpha or beta.
• --time-window, -t. The time window for which to show log information. You can use both
exact timestamps and relative offsets. You must provide this information in the format <begin-
time>,<end-time>. If you do not specify either the begin time or the end time, then the value
for that option defaults to the current system date and time. Use a separate argument for each
additional time window to specify.
Greengrass CLI supports the following formats for timestamps:
• yyyy-MM-DD, for example, 2020-06-30. The time defaults to 00:00:00 when you use this
format.
yyyyMMDD, for example, 20200630. The time defaults to 00:00:00 when you use this format.
HH:mm:ss, for example, 15:30:45. The date defaults to the current system date when you use
this format.
HH:mm:ssSSS, for example, 15:30:45. The date defaults the current system date when you
use this format.
YYYY-MM-DD'T'HH:mm:ss'Z', for example, 2020-06-30T15:30:45Z.
YYYY-MM-DD'T'HH:mm:ss, for example, 2020-06-30T15:30:45.
yyyy-MM-dd'T'HH:mm:ss.SSS, for example, 2020-06-30T15:30:45.250.
Relative offsets specify a time period offset from the current system time. Greengrass CLI supports
the following format for relative offsets: +|-[<value>h|hr|hours][valuem|min|minutes]
[value]s|sec|seconds.
For example, the following argument to specify a time window between 1 hour and 2 hours 15
minutes before the current time is --time-window -2h15min,-1hr.
437
AWS IoT Greengrass Developer Guide, Version 2
Greengrass CLI commands
• --verbose. Show all fields from the log messages. Do not use with --syslog.
• --no-color, -nc. Remove color coding. The default color coding for log messages uses bold red
text. Supports only UNIX-like terminals because it uses ANSI escape sequences.
• --before, -b. The number of lines to show preceding a matched log entry. Default is 0.
• --after, -a. The number of lines to show following a matched log entry. Default is 0.
• --syslog. Process all log files using the syslog protocol defined by RFC3164. Do not use with
--log-dir and --verbose. The syslog protocol uses the following format: "<$Priority>
$Timestamp $Host $Logger ($Class): $Message". If you do not specify a log file, then
Greengrass CLI reads log messages from the following locations: /var/log/messages, /var/
log/syslog, or the /var/log/system.log.
AWS IoT Greengrass doesn't currently support this feature on Windows core devices.
• --max-log-queue-size, -m. The maximum number of log entries to allocate to memory. Use
this option to optimize memory usage. Default is 100.
Output
The following example shows the output produced when you run this command.
$ sudo greengrass-cli logs get --verbose \
--log-file /greengrass/v2/logs/greengrass.log \
--filter deployment,serviceName=DeploymentService \
--filter level=INFO \
--time-window 2020-12-08T01:11:17,2020-12-08T01:11:22
2020-12-08T01:11:17.615Z [INFO] (pool-2-thread-14)
com.aws.greengrass.deployment.DeploymentService: Current deployment finished.
{DeploymentId=44d89f46-1a29-4044-ad89-5151213dfcbc, serviceName=DeploymentService,
currentState=RUNNING}
2020-12-08T01:11:17.675Z [INFO] (pool-2-thread-14)
com.aws.greengrass.deployment.IotJobsHelper: Updating status of persisted
deployment. {Status=SUCCEEDED, StatusDetails={detailed-deployment-status=SUCCESSFUL},
ThingName=MyThing, JobId=22d89f46-1a29-4044-ad89-5151213dfcbc
list-keywords
Show suggested keywords that you can use to filter log files.
Synopsis
greengrass-cli logs list-keywords [arguments]
Arguments
None
Output
The following examples show the output produced when you run this command.
$ sudo greengrass-cli logs list-keywords
Here is a list of suggested keywords for Greengrass log:
level=$str
thread=$str
loggerName=$str
eventType=$str
serviceName=$str
438
AWS IoT Greengrass Developer Guide, Version 2
Greengrass CLI commands
error=$str
$ sudo greengrass-cli logs list-keywords --syslog
Here is a list of suggested keywords for syslog:
priority=$int
host=$str
logger=$str
class=$str
list-log-files
Show log files located in a specified directory.
Synopsis
greengrass-cli logs list-log-files [arguments]
Arguments
--log-dir, -ld. The path to the directory to check for log files.
Output
The following example shows the output produced when you run this command.
$ sudo greengrass-cli logs list-log-files -ld /greengrass/v2/logs/
/greengrass/v2/logs/aws.greengrass.Nucleus.log
/greengrass/v2/logs/main.log
/greengrass/v2/logs/greengrass.log
Total 3 files found.
get-debug-password
Use the get-debug-password command to print a randomly generated password for the local debug
console component (p. 265) (aws.greengrass.LocalDebugConsole). The password expires 8 hours
after it is generated.
Synopsis
greengrass-cli get-debug-password
Arguments
None
Output
The following example shows the output produced when you run this command.
$ sudo greengrass-cli get-debug-password
Username: debug
Password: KPr01f9M4uMj6Arq2mxTZJ6mU7PpiczaCeg6y6Omp5A
Password will expire at: 2020-11-17T16:46:59.772539-08:00
439
AWS IoT Greengrass Developer Guide, Version 2
Develop AWS IoT Greengrass
components
AWS IoT Greengrass components are software modules that you deploy to Greengrass core devices.
Components can represent applications, runtime installers, libraries, or any code that you would run on a
device. You can define components that depend on other components. For example, you might define a
component that installs Python, and then define that component as a dependency of your components
that run Python applications. When you deploy your components to your fleets of devices, Greengrass
deploys only the software modules that your devices require.
You can develop and test components on your Greengrass core device. As a result, you can create and
iterate your AWS IoT Greengrass software without interacting with the AWS Cloud. When you finish a
version of your component, you can upload it to AWS IoT Greengrass in the cloud, so you and your team
can deploy the component to other devices in your fleet. For more information about how to deploy
components, see Deploy AWS IoT Greengrass components to devices (p. 491).
Every component is composed of a recipe and artifacts.
• Recipes
Every component contains a recipe file, which defines its metadata. The recipe also specifies
the component's configuration parameters, component dependencies, lifecycle, and platform
compatibility. The component lifecycle defines the commands that install, run, and shut down the
component. For more information, see AWS IoT Greengrass component recipe reference (p. 471).
You can define recipes in JSON or YAML format.
• Artifacts
Components can have any number of artifacts, which are component binaries. Artifacts can include
scripts, compiled code, static resources, and any other files that a component consumes. Components
can also consume artifacts from component dependencies.
AWS IoT Greengrass provides pre-built components that you can use in your applications and deploy
to your devices. For example, you can use the stream manager component to upload data to various
AWS services, or you can use the CloudWatch metrics component to publish custom metrics to Amazon
CloudWatch. For more information, see AWS-provided components (p. 175).
AWS IoT Greengrass curates an index of Greengrass components, called the Greengrass Software
Catalog. This catalog tracks Greengrass components that are developed by the Greengrass community.
From this catalog, you can download, modify, and deploy components to create your Greengrass
applications. For more information, see Community components (p. 419).
The AWS IoT Greengrass Core software runs components as the system user and group, such as
ggc_user and ggc_group, that you configure on the core device. This means that components have the
permissions of that system user. If you use a system user without a home directory, then components
can't use run commands or code that use a home directory. This means that you can't use the pip
install some-library --user command to install Python packages for example. If you followed
the getting started tutorial (p. 31) to set up your core device, then your system user doesn't have a home
directory. For more information about how to configure the user and group that run components, see
Configure the user that runs components (p. 161).
Note
AWS IoT Greengrass uses semantic versions for components. Semantic versions follow a
major.minor.patch number system. For example, version 1.0.0 represents the first major
release for a component. For more information, see the semantic version specification.
440
AWS IoT Greengrass Developer Guide, Version 2
Component lifecycle
Topics
• Component lifecycle (p. 441)
• Component types (p. 441)
• Create AWS IoT Greengrass components (p. 442)
• Test AWS IoT Greengrass components with local deployments (p. 449)
• Publish components to deploy to your core devices (p. 451)
• Interact with AWS services (p. 454)
• Run a Docker container (p. 456)
• AWS IoT Greengrass component recipe reference (p. 471)
• Component environment variable reference (p. 489)
Component lifecycle
The component lifecycle defines the stages that the AWS IoT Greengrass Core software uses to install and
run components. Each stage defines a script and other information that specifies how the component
behaves. For example, when you install a component, the AWS IoT Greengrass Core software runs the
Install lifecycle script for that component. Components on core devices have the following lifecycle
states:
• NEW – The component's recipe and artifacts are loaded on the core device, but the component
isn't installed. After a component enters this state, it runs its bootstrap (p. 476) and install
scripts (p. 477).
• INSTALLED – The component is installed on the core device. The component enters this state after it
runs its install script (p. 477).
• STARTING – The component is starting on the core device. The component enters this state when it
runs its startup script (p. 478). If the startup succeeds, the component enters the RUNNING state.
• RUNNING – The component is running on the core device. The component enters this state when it
runs its run script (p. 477) or when it has active background processes from its startup script.
• FINISHED – The component ran successfully and completed its run.
• STOPPING – The component is stopping. The component enters this state when it runs its shutdown
script (p. 479).
• ERRORED – The component encountered an error. When the component enters this state, it runs
its recover script (p. 480). Then, the component restarts to try returning to normal use. If the
component enters the ERRORED state three times without a successful run, the component becomes
BROKEN.
• BROKEN – The component encountered errors multiple times and can't recover. You must deploy the
component again to fix it.
Component types
The component type specifies how the AWS IoT Greengrass Core software runs the component.
Components can have the following types:
• Nucleus (aws.greengrass.nucleus)
The Greengrass nucleus is the component that provides the minimum functionality of the AWS IoT
Greengrass Core software. For more information, see Greengrass nucleus (p. 181).
• Plugin (aws.greengrass.plugin)
441
AWS IoT Greengrass Developer Guide, Version 2
Create components
The Greengrass nucleus runs a plugin component in the same Java Virtual Machine (JVM) as the
nucleus. The nucleus restarts when you change the version of a plugin component on a core device.
To install and run plugin components, you must configure the Greengrass nucleus to run as a system
service. For more information, see Configure the Greengrass nucleus as a system service (p. 158).
Several components that are provided by AWS are plugin components, which enables them to
interface directly with the Greengrass nucleus. Plugin components use the same log file as the
Greengrass nucleus. For more information, see Monitor AWS IoT Greengrass logs (p. 506).
• Generic (aws.greengrass.generic)
The Greengrass nucleus runs a generic component's lifecycle scripts, if the component defines a
lifecycle.
This type is the default type for custom components.
• Lambda (aws.greengrass.lambda)
The Greengrass nucleus runs a Lambda function component using the Lambda launcher
component (p. 252).
When you create a component from a Lambda function, the component has this type. For more
information, see Run AWS Lambda functions (p. 523).
Note
We don't recommend that you specify the component type in a recipe. AWS IoT Greengrass sets
the type for you when you create a component.
Create AWS IoT Greengrass components
You can develop custom AWS IoT Greengrass components on a local development computer or a
Greengrass core device. AWS IoT Greengrass provides the AWS IoT Greengrass Development Kit
Command-Line Interface (GDK CLI) (p. 420) to help you create, build, and publish components from
predefined component templates and community components (p. 419). You can also run built-in shell
commands to create, build, and publish components. Choose from the following options to create
custom Greengrass components:
• Use the Greengrass Development Kit CLI
Use the GDK CLI to develop components on a local development computer. The GDK CLI builds
and packages component source code into a recipe and artifacts that you can publish as a private
component to the AWS IoT Greengrass service. You can configure the GDK CLI to automatically
update the component's version and artifact URIs when you publish the component, so you don't
need to update the recipe each time. To develop a component using the GDK CLI, you can start from
a template or a community component from the Greengrass Software Catalog (p. 419). For more
information, see AWS IoT Greengrass Development Kit Command-Line Interface (p. 420).
• Run built-in shell commands
You can run built-in shell commands to develop components on a local development computer or
on a Greengrass core device. You use shell commands to copy or build component source code into
artifacts. Each time you create a new version of a component, you must create or update the recipe
with the new component version. When you publish the component to the AWS IoT Greengrass
service, you must update the URI to each component artifact in the recipe.
Topics
442
AWS IoT Greengrass Developer Guide, Version 2
Create a component (GDK CLI)
• Create a component (GDK CLI) (p. 443)
• Create a component (shell commands) (p. 447)
Create a component (GDK CLI)
Follow instructions in this section to create and build a component using the GDK CLI.
To develop a Greengrass component (GDK CLI)
1. If you haven't already, install the GDK CLI on your development computer. For more information, see
Install the AWS IoT Greengrass Development Kit Command-Line Interface (p. 421).
2. Change to the folder where you want to create component folders.
Linux or Unix
mkdir ~/greengrassv2
cd ~/greengrassv2
Windows Command Prompt (CMD)
mkdir %USERPROFILE%\greengrassv2
cd %USERPROFILE%\greengrassv2
PowerShell
mkdir ~/greengrassv2
cd ~/greengrassv2
3. Choose a component template or community component to download. The GDK CLI downloads the
template or community component, so you can start from a functional example. Use the component
list (p. 425) command to retrieve the list of available templates or community components.
• To list component templates, run the following command. Each line in the response includes a
template's name and programming language.
gdk component list --template
• To list community components, run the following command.
gdk component list --repository
4. Create and change to a component folder where the GDK CLI downloads the template or community
component. Replace HelloWorld-python with the name of the component, or another name that
helps you identify this component folder.
Linux or Unix
mkdir HelloWorld-python
cd HelloWorld-python
Windows Command Prompt (CMD)
mkdir HelloWorld-python
cd HelloWorld-python
443
AWS IoT Greengrass Developer Guide, Version 2
Create a component (GDK CLI)
PowerShell
mkdir HelloWorld-python
cd HelloWorld-python
5. Download the template or community component to the current folder. Use the component
init (p. 422) command.
• To create a component folder from a template, run the following command. Replace
HelloWorld with the name of the template, and replace python with the name of the
programming language.
gdk component init --template HelloWorld --language python
• To create a component folder from a community component, run the following command.
Replace ComponentName with the name of the community component.
gdk component init --repository ComponentName
Note
You must run the gdk component init command in an empty folder. The GDK CLI
downloads the template or community component to the current folder.
6. The GDK CLI reads from the GDK CLI configuration file (p. 425), named gdk-config.json, to build
and publish components. This configuration file exists in the root of the component folder. The
previous step creates this file for you. In this step, you update gdk-config.json with information
about your component. Do the following:
a. Open gdk-config.json in a text editor.
b. (Optional) Change the name of the component. The component name is the key in the
component object.
c. Change the author of the component.
d. (Optional) Change the version of the component. Specify one of the following:
• NEXT_PATCH – When you choose this option, the GDK CLI sets the version when you publish
the component. The GDK CLI queries the AWS IoT Greengrass service to identify the latest
published version of the component. Then, it sets the version to the next patch version after
that version. If you haven't published the component before, the GDK CLI uses version 1.0.0.
If you choose this option, you can't use the Greengrass CLI (p. 225) to locally deploy and test
the component to your local development computer that runs the AWS IoT Greengrass Core
software. To enable local deployments, you must specify a semantic version instead.
• A semantic version, such as 1.0.0. Semantic versions use a major.minor.patch numbering
system. For more information, see the semantic version specification.
If you develop components on a Greengrass core device where you want to deploy and test
the component, choose this option. You must build the component with a specific version to
create local deployments with the Greengrass CLI (p. 225)
e. (Optional) Change the build configuration for the component. The build configuration defines
how the GDK CLI builds the component's source into artifacts. Choose from the following
options for build_system:
• zip – Packages the component's source into a ZIP file to define as the component's only
artifact. Choose this option for the following types of components:
• Components that use interpreted programming languages, such as Python or JavaScript.
• Components that package files other than code, such as machine learning models or other
resources.
444
AWS IoT Greengrass Developer Guide, Version 2
Create a component (GDK CLI)
When you use the zip build system, the GDK CLI zips the contents in the component's source
folder, except the following:
• The gdk-config.json file
• The recipe file (recipe.json or recipe.yaml)
• Build folders, such as greengrass-build
• maven – Runs the mvn clean package command to build the component's source into
artifacts. Choose this option for components that use Maven, such as Java components.
• gradle – Runs the gradle build command to build the component's source into artifacts.
Choose this option for components that use Gradle.
• custom – Runs a custom command to build the component's source into artifacts. Specify the
custom command in the custom_build_command parameter.
f. If you specify custom for build_system, add the custom_build_command to the build
object. In custom_build_command, specify a single string or list of strings, where each string
is a word in the command. For example, to run a custom build command for a C++ component,
you might specify ["cmake", "--build", "build", "--config", "Release"].
g. The GDK CLI uploads to the S3 bucket whose name is bucketName-region-accountId,
where bucketName and region are the values that you specify in gdk-config.json. The
GDK CLI creates the bucket if it doesn't exist.
Change the publish configuration for the component. Do the following:
i. Specify the name of the S3 bucket to use to host component artifacts.
ii. Specify the AWS Region where the GDK CLI publishes the component.
When you're done with this step, the gdk-config.json file might look similar to the following
example.
{
"component": {
"com.example.PythonHelloWorld": {
"author": "Amazon",
"version": "NEXT_PATCH",
"build": {
"build_system" : "zip"
},
"publish": {
"bucket": "greengrass-component-artifacts",
"region": "us-west-2"
}
}
},
"gdk_version": "1.0.0"
}
7. Update the component recipe file, named recipe.yaml or recipe.json. You can update the
component description, default configuration, lifecycle scripts, and platform support. For more
information, see AWS IoT Greengrass component recipe reference (p. 471).
Important
When you use the GDK CLI, recipe attribute names are case sensitive and must match the
capitalization in the component recipe reference (p. 471).
When you're done with this step, the recipe file might look similar to the following example.
445
AWS IoT Greengrass Developer Guide, Version 2
Create a component (GDK CLI)
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "{COMPONENT_NAME}",
"ComponentVersion": "{COMPONENT_VERSION}",
"ComponentDescription": "This is simple Hello World component written in
Python.",
"ComponentPublisher": "{COMPONENT_AUTHOR}",
"ComponentConfiguration": {
"DefaultConfiguration": {
"Message": "World"
}
},
"Manifests": [
{
"Platform": {
"os": "all"
},
"Artifacts": [
{
"URI": "s3://{COMPONENT_NAME}/{COMPONENT_VERSION}/HelloWorld.zip",
"Unarchive": "ZIP"
}
],
"Lifecycle": {
"Run": "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py
{configuration:/Message}"
}
}
]
}
YAML
---
RecipeFormatVersion: "2020-01-25"
ComponentName: "{COMPONENT_NAME}"
ComponentVersion: "{COMPONENT_VERSION}"
ComponentDescription: "This is simple Hello World component written in Python."
ComponentPublisher: "{COMPONENT_AUTHOR}"
ComponentConfiguration:
DefaultConfiguration:
Message: "World"
Manifests:
- Platform:
os: all
Artifacts:
- URI: "s3://BUCKET_NAME/COMPONENT_NAME/COMPONENT_VERSION/HelloWorld.zip"
Unarchive: ZIP
Lifecycle:
Run: "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py
{configuration:/Message}"
8. Develop and build the Greengrass component. The component build (p. 423) command produces a
recipe and artifacts in the greengrass-build folder in the component folder. Run the following
command.
gdk component build
446
AWS IoT Greengrass Developer Guide, Version 2
Create a component (shell commands)
When you're ready to test your component, use the GDK CLI to publish it to the AWS IoT Greengrass
service. Then, you can deploy the component to Greengrass core devices. For more information, see
Publish components to deploy to your core devices (p. 451).
Create a component (shell commands)
Follow instructions in this section to create recipe and artifact folders that contain source code and
artifacts for multiple components.
To develop a Greengrass component (shell commands)
1. Create a folder for your components with subfolders for recipes and artifacts. Run the following
commands on your Greengrass core device to create these folders and change to the component
folder. Replace ~/greengrassv2 or %USERPROFILE%\greengrassv2 with the path to the folder
to use for local development.
Linux or Unix
mkdir -p ~/greengrassv2/{recipes,artifacts}
cd ~/greengrassv2
Windows Command Prompt (CMD)
mkdir %USERPROFILE%\greengrassv2\recipes, %USERPROFILE%\greengrassv2\artifacts
cd %USERPROFILE%\greengrassv2
PowerShell
mkdir ~/greengrassv2/recipes, ~/greengrassv2/artifacts
cd ~/greengrassv2
2. Use a text editor to create a recipe file that defines your component's metadata, parameters,
dependencies, lifecycle, and platform capability. Include the component version in the recipe file
name so that you can identify which recipe reflects which component version. You can choose YAML
or JSON format for your recipe.
For example, on a Linux-based system, you can run the following command to use GNU nano to
create the file.
JSON
nano recipes/com.example.HelloWorld-1.0.0.json
YAML
nano recipes/com.example.HelloWorld-1.0.0.yaml
Note
AWS IoT Greengrass uses semantic versions for components. Semantic versions follow a
major.minor.patch number system. For example, version 1.0.0 represents the first major
release for a component. For more information, see the semantic version specification.
3. Define the recipe for your component. For more information, see AWS IoT Greengrass component
recipe reference (p. 471).
Your recipe might look similar to the following Hello World example recipe.
447
AWS IoT Greengrass Developer Guide, Version 2
Create a component (shell commands)
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.HelloWorld",
"ComponentVersion": "1.0.0",
"ComponentDescription": "My first AWS IoT Greengrass component.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"Message": "world"
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"Run": "python3 -u {artifacts:path}/hello_world.py \"{configuration:/
Message}\""
}
},
{
"Platform": {
"os": "windows"
},
"Lifecycle": {
"Run": "py -3 -u {artifacts:path}/hello_world.py \"{configuration:/
Message}\""
}
}
]
}
YAML
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.HelloWorld
ComponentVersion: '1.0.0'
ComponentDescription: My first AWS IoT Greengrass component.
ComponentPublisher: Amazon
ComponentConfiguration:
DefaultConfiguration:
Message: world
Manifests:
- Platform:
os: linux
Lifecycle:
Run: |
python3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
- Platform:
os: windows
Lifecycle:
Run: |
py -3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
This recipe runs a Hello World Python script, which might look similar to the following example
script.
448
AWS IoT Greengrass Developer Guide, Version 2
Test components with local deployments
import sys
message = "Hello, %s!" % sys.argv[1]
# Print the message to stdout, which Greengrass saves in a log file.
print(message)
4. Create a folder for the component version to develop. We recommend that you use a separate
folder for each component version's artifacts so that you can identify which artifacts are for each
component version. Run the following command.
Linux or Unix
mkdir -p artifacts/com.example.HelloWorld/1.0.0
Windows Command Prompt (CMD)
mkdir artifacts/com.example.HelloWorld/1.0.0
PowerShell
mkdir artifacts/com.example.HelloWorld/1.0.0
Important
You must use the following format for the artifact folder path. Include the component
name and version that you specify in the recipe.
artifacts/componentName/componentVersion/
5. Create the artifacts for your component in the folder that you created in the previous step. Artifacts
can include software, images, and any other binaries that your component uses.
When your component is ready, test your component (p. 449).
Test AWS IoT Greengrass components with local
deployments
If you develop a Greengrass component on a core device, you can create a local deployment to install
and test it. Follow the steps in this section to create a local deployment.
If you develop the component on a different computer, such as a local development computer, you can't
create a local deployment. Instead, publish the component to the AWS IoT Greengrass service so that
you can deploy it to Greengrass core devices to test it. For more information, see Publish components to
deploy to your core devices (p. 451) and Deploy AWS IoT Greengrass components to devices (p. 491).
To test a component on an Greengrass core device
1. The core device logs events such as component updates. You can view this log file to discover
and troubleshoot errors with your component, such as an invalid recipe. This log file also displays
messages that your component prints to standard out (stdout). We recommend that you open an
additional terminal session on your core device to observe new log messages in real time. Open
449
AWS IoT Greengrass Developer Guide, Version 2
Test components with local deployments
a new terminal session, such as through SSH, and run the following command to view the logs.
Replace /greengrass/v2 with the path to the AWS IoT Greengrass root folder.
Linux or Unix
sudo tail -f /greengrass/v2/logs/greengrass.log
PowerShell
gc C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
You can also view the log file for your component.
Linux or Unix
sudo tail -f /greengrass/v2/logs/com.example.HelloWorld.log
PowerShell
gc C:\greengrass\v2\logs\com.example.HelloWorld.log -Tail 10 -Wait
2. In your original terminal session, run the following command to update the core device with your
component. Replace /greengrass/v2 with the path to the AWS IoT Greengrass root folder, and
replace ~/greengrassv2 with the path to your local development folder.
Linux or Unix
sudo /greengrass/v2/bin/greengrass-cli deployment create \
--recipeDir ~/greengrassv2/recipes \
--artifactDir ~/greengrassv2/artifacts \
--merge "com.example.HelloWorld=1.0.0"
Windows Cmmand Prompt (CMD)
C:\greengrass\v2\bin\greengrass-cli deployment create ^
--recipeDir %USERPROFILE%\greengrassv2\recipes ^
--artifactDir %USERPROFILE%\greengrassv2\artifacts ^
--merge "com.example.HelloWorld=1.0.0"
PowerShell
C:\greengrass\v2\bin\greengrass-cli deployment create `
--recipeDir ~/greengrassv2/recipes `
--artifactDir ~/greengrassv2/artifacts `
--merge "com.example.HelloWorld=1.0.0"
Note
You can also use the greengrass-cli deployment create command to set the value
of your component's configuration parameters. For more information, see create (p. 434).
3. Test your component as it runs on the Greengrass core device. When you finish this version of
your component, you can upload it to the AWS IoT Greengrass service. Then, you can deploy the
component to other core devices. For more information, see Publish components to deploy to your
core devices (p. 451).
450
AWS IoT Greengrass Developer Guide, Version 2
Publish components to deploy
Publish components to deploy to your core devices
After you build or complete a version of a component, you can publish it to the AWS IoT Greengrass
service. Then, you can deploy it to Greengrass core devices.
If you use the Greengrass Development Kit CLI (GDK CLI) (p. 420) to develop and build a
component (p. 442), you can use the GDK CLI (p. 451) to publish the component to the AWS Cloud.
Otherwise, use built-in shell commands and the AWS CLI (p. 452) to publish the component.
Topics
• Publish a component (GDK CLI) (p. 451)
• Publish a component (shell commands) (p. 452)
Publish a component (GDK CLI)
Follow instructions in this section to publish a component using the GDK CLI. The GDK CLI uploads build
artifacts to an S3 bucket, updates the artifact URIs in the recipe, and creates the component from the
recipe. You specify the S3 bucket and Region to use in the GDK CLI configuration file (p. 425).
The GDK CLI uploads to the S3 bucket whose name is bucketName-region-accountId, where
bucketName and region are the values that you specify in gdk-config.json. The GDK CLI creates the
bucket if it doesn't exist.
Important
Core device roles don't allow access to S3 buckets by default. If this is your first time using this
S3 bucket, you must add permissions to the role to allow core devices to retrieve component
artifacts from this S3 bucket. For more information, see Allow access to S3 buckets for
component artifacts (p. 792).
To publish a Greengrass component (GDK CLI)
1. Open the component folder in a command prompt or terminal.
2. If you haven't already, build the Greengrass component. The component build (p. 423) command
produces a recipe and artifacts in the greengrass-build folder in the component folder. Run the
following command.
gdk component build
3. Publish the component to the AWS Cloud. The component publish (p. 424) command uploads the
component's artifacts to Amazon S3 and updates the component's recipe with each artifact's URI.
Then, it creates the component in the AWS IoT Greengrass service.
Note
AWS IoT Greengrass computes the digest of each artifact when you create the component.
This means that you can't modify the artifact files in your S3 bucket after you create a
component. If you do, deployments that include this component will fail, because the file
digest doesn't match. If you modify an artifact file, you must create a new version of the
component.
If you specify NEXT_PATCH for the component version in the GDK CLI configuration file, the GDK CLI
uses the next patch version that doesn't already exist in the AWS IoT Greengrass service.
Run the following command.
gdk component publish
451
AWS IoT Greengrass Developer Guide, Version 2
Publish a component (shell commands)
The output tells you the version of the component that the GDK CLI created.
After you publish the component, you can deploy the component to core devices. For more
information, see Deploy AWS IoT Greengrass components to devices (p. 491).
Publish a component (shell commands)
Use the following procedure to publish a component using shell commands and the AWS Command Line
Interface (AWS CLI). When you publish a component, you do the following:
1. Publish component artifacts to an S3 bucket.
2. Add each artifact's Amazon S3 URI to the component recipe.
3. Create a component version in AWS IoT Greengrass from the component recipe.
Note
Each component version that you upload must be unique. Make sure that you upload the correct
component version, because you can't edit it after you upload it.
You can follow these steps to publish a component from your development computer or your Greengrass
core device.
To publish a component (shell commands)
1. If the component uses a version that exists in the AWS IoT Greengrass service, then you must change
the version of the component. Open the recipe in a text editor, increment the version, and save the
file. Choose a new version that reflects the changes that you made to the component.
Note
AWS IoT Greengrass uses semantic versions for components. Semantic versions follow a
major.minor.patch number system. For example, version 1.0.0 represents the first major
release for a component. For more information, see the semantic version specification.
2. If your component has artifacts, do the following:
a. Publish the component's artifacts to an S3 bucket in your AWS account.
Tip
We recommend that you include the component name and version in the path to the
artifact in the S3 bucket. This naming scheme can help you maintain the artifacts
that previous versions of the component use, so you can continue to support previous
component versions.
Run the following command to publish an artifact file to an S3 bucket. Replace
DOC-EXAMPLE-BUCKET with the name of the bucket, and replace artifacts/
com.example.HelloWorld/1.0.0/artifact.py with the path to the artifact file.
aws s3 cp artifacts/com.example.HelloWorld/1.0.0/artifact.py s3://DOC-EXAMPLE-
BUCKET/artifacts/com.example.HelloWorld/1.0.0/artifact.py
Important
Core device roles don't allow access to S3 buckets by default. If this is your first time
using this S3 bucket, you must add permissions to the role to allow core devices to
retrieve component artifacts from this S3 bucket. For more information, see Allow
access to S3 buckets for component artifacts (p. 792).
452
AWS IoT Greengrass Developer Guide, Version 2
Publish a component (shell commands)
b. Add a list named Artifacts to the component recipe if it isn't present. The Artifacts list
appears in each manifest, which defines the component's requirements on each platform that it
supports (or the component's default requirements for all platforms).
c. Add each artifact to the list of artifacts, or update the URI of existing artifacts. The Amazon
S3 URI is composed of the bucket name and the path to the artifact object in the bucket. Your
artifacts' Amazon S3 URIs should look similar to the following example.
s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/artifact.py
After you complete these steps, your recipe should have an Artifacts list that looks like the
following.
JSON
{
...
"Manifests": [
{
"Lifecycle": {
...
},
"Artifacts": [
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/MyGreengrassComponent/1.0.0/
artifact.py",
"Unarchive": "NONE"
}
]
}
]
}
Note
You can add the "Unarchive": "ZIP" option for a ZIP artifact to configure the AWS
IoT Greengrass Core software to unzip the artifact when the component deploys.
YAML
...
Manifests:
- Lifecycle:
...
Artifacts:
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/MyGreengrassComponent/1.0.0/
artifact.py
Unarchive: NONE
Note
You can use the Unarchive: ZIP option to configure the AWS IoT Greengrass Core
software to unzip a ZIP artifact when the component deploys. For more information
about how to use ZIP artifacts in a component, see the artifacts:decompressedPath
recipe variable (p. 485).
For more information about recipes, see AWS IoT Greengrass component recipe reference (p. 471).
3. Use the AWS IoT Greengrass console to create a component from the recipe file.
453
AWS IoT Greengrass Developer Guide, Version 2
Interact with AWS services
Run the following command to create the component from a recipe file. This command creates
the component and publishes it as a private AWS IoT Greengrass component in your AWS account.
Replace path/to/recipeFile with the path to the recipe file.
aws greengrassv2 create-component-version --inline-recipe fileb://path/to/recipeFile
Copy the arn from the response to check the state of the component in the next step.
Note
AWS IoT Greengrass computes the digest of each artifact when you create the component.
This means that you can't modify the artifact files in your S3 bucket after you create a
component. If you do, deployments that include this component will fail, because the file
digest doesn't match. If you modify an artifact file, you must create a new version of the
component.
4. Each component in the AWS IoT Greengrass service has a state. Run the following command
to confirm the state of the component version that you publish in this procedure. Replace
com.example.HelloWorld and 1.0.0 with the component version to query. Replace the arn with
the ARN from the previous step.
aws greengrassv2 describe-component --arn "arn:aws:greengrass:region:account-
id:components:com.example.HelloWorld:versions:1.0.0"
The operation returns a response that contains the component's metadata. The metadata contains a
status object that contains the component state and any errors, if applicable.
When the component state is DEPLOYABLE, you can deploy the component to devices. For more
information, see Deploy AWS IoT Greengrass components to devices (p. 491).
Interact with AWS services
Greengrass core devices use X.509 certificates to connect to AWS IoT Core using TLS mutual
authentication protocols. These certificates let devices interact with AWS IoT without AWS credentials,
which typically comprise an access key ID and a secret access key. Other AWS services require AWS
credentials instead of X.509 certificates to call API operations at service endpoints. AWS IoT Core has
a credentials provider that enables devices to use their X.509 certificate to authenticate AWS requests.
The AWS IoT credentials provider authenticates devices using an X.509 certificate and issues AWS
credentials in the form a temporary, limited-privilege security token. Devices can use this token to sign
and authenticate any AWS request. This eliminates the need to store AWS credentials on Greengrass core
devices. For more information, see Authorizing direct calls to AWS services in the AWS IoT Core Developer
Guide.
To fetch credentials from AWS IoT, Greengrass, core devices use an AWS IoT role alias that points to an
IAM role. This IAM role is called the token exchange role. You create the role alias and token exchange role
when you install the AWS IoT Greengrass Core software. To specify the role alias that a core device uses,
configure the iotRoleAlias parameter of the Greengrass nucleus (p. 181).
The AWS IoT credentials provider assumes the token exchange role on your behalf to provide AWS
credentials to core devices. You can attach appropriate IAM policies to this role to allow your core
devices access to your AWS resources, such as components artifacts in S3 buckets. For more information
about how to configure the token exchange role, see Authorize core devices to interact with AWS
services (p. 790).
Greengrass core devices store AWS credentials in memory, and the credentials expire after an hour by
default. If the AWS IoT Greengrass Core software restarts, it must fetch credentials again. You can use
the UpdateRoleAlias operation to configure the duration that credentials are valid.
454
AWS IoT Greengrass Developer Guide, Version 2
Interact with AWS services
AWS IoT Greengrass provides a public component, the token exchange service component,
that you can define as a dependency in your custom component to interact with AWS
services. The token exchange service provides your component with an environment variable,
AWS_CONTAINER_CREDENTIALS_FULL_URI, that defines the URI to a local server that provides AWS
credentials. When you create an AWS SDK client, the client checks for this environment variable and
connects to the local server to retrieve AWS credentials and uses them to sign API requests. This lets you
use AWS SDKs and other tools to call AWS services in your components. For more information, see Token
exchange service (p. 407).
Important
Support to acquire AWS credentials in this way was added to the AWS SDKs on July 13th, 2016.
Your component must use an AWS SDK version that was created on or after that date. For more
information, see Using a supported AWS SDK in the Amazon Elastic Container Service Developer
Guide.
To acquire AWS credentials in your custom component, define
aws.greengrass.TokenExchangeService as a dependency in the component recipe. The following
example recipe defines a component that installs boto3 and runs a Python script that uses AWS
credentials from the token exchange service to list Amazon S3 buckets.
Note
To run this example component, your device must have the s3:ListAllMyBuckets
permission. For more information, see Authorize core devices to interact with AWS
services (p. 790).
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.ListS3Buckets",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that uses the token exchange service to list S3
buckets.",
"ComponentPublisher": "Amazon",
"ComponentDependencies": {
"aws.greengrass.TokenExchangeService": {
"VersionRequirement": "^2.0.0",
"DependencyType": "HARD"
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"Install": "pip3 install --user boto3",
"Run": "python3 -u {artifacts:path}/list_s3_buckets.py"
}
},
{
"Platform": {
"os": "windows"
},
"Lifecycle": {
"Install": "pip3 install --user boto3",
"Run": "py -3 -u {artifacts:path}/list_s3_buckets.py"
}
}
]
}
455
AWS IoT Greengrass Developer Guide, Version 2
Run a Docker container
YAML
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.ListS3Buckets
ComponentVersion: '1.0.0'
ComponentDescription: A component that uses the token exchange service to list S3
buckets.
ComponentPublisher: Amazon
ComponentDependencies:
aws.greengrass.TokenExchangeService:
VersionRequirement: '^2.0.0'
DependencyType: HARD
Manifests:
- Platform:
os: linux
Lifecycle:
Install:
pip3 install --user boto3
Run: |-
python3 -u {artifacts:path}/list_s3_buckets.py
- Platform:
os: windows
Lifecycle:
Install:
pip3 install --user boto3
Run: |-
py -3 -u {artifacts:path}/list_s3_buckets.py
This example component runs the following Python script, list_s3_buckets.py that lists Amazon S3
buckets.
import boto3
import os
try:
print("Creating boto3 S3 client...")
s3 = boto3.client('s3')
print("Successfully created boto3 S3 client")
except Exception as e:
print("Failed to create boto3 s3 client. Error: " + str(e))
exit(1)
try:
print("Listing S3 buckets...")
response = s3.list_buckets()
for bucket in response['Buckets']:
print(f'\t{bucket["Name"]}')
print("Successfully listed S3 buckets")
except Exception as e:
print("Failed to list S3 buckets. Error: " + str(e))
exit(1)
Run a Docker container
You can configure AWS IoT Greengrass components to run a Docker container from images stored in the
following locations:
• Public and private image repositories in Amazon Elastic Container Registry (Amazon ECR)
456
AWS IoT Greengrass Developer Guide, Version 2
Requirements
• Public Docker Hub repository
• Public Docker Trusted Registry
• S3 bucket
In your custom component, include the Docker image URI as an artifact to retrieve the image and run
it on the core device. For Amazon ECR and Docker Hub images, you can use the Docker application
manager (p. 216) component to download the images and manage credentials for private Amazon ECR
repositories.
Topics
• Requirements (p. 457)
• Run a Docker container from a public image in Amazon ECR or Docker Hub (p. 459)
• Run a Docker container from a private image in Amazon ECR (p. 461)
• Run a Docker container from an image in Amazon S3 (p. 463)
• Use interprocess communication in Docker container components (p. 465)
• Use AWS credentials in Docker container components (Linux) (p. 467)
• Use stream manager in Docker container components (Linux) (p. 469)
Requirements
To run a Docker container in a component, you need the following:
• A Greengrass core device. If you don't have one, see Getting started with AWS IoT Greengrass
V2 (p. 31).
• Docker Engine 1.9.1 or later installed on your Greengrass core device. Version 20.10 is the latest
version that is verified to work with the connector. You must install Docker directly on the core device
before you deploy custom components that run Docker containers.
Tip
You can also configure the core device to install Docker Engine when the component installs.
For example, the following install script installs Docker Engine before it loads the Docker
image. This install script works on Debian-based Linux distributions, such as Ubuntu. If
you configure the component to install Docker Engine with this command, you may need
to set RequiresPrivilege to true in the lifecycle script to run the installation and
docker commands. For more information, see AWS IoT Greengrass component recipe
reference (p. 471).
apt-get install docker-ce docker-ce-cli containerd.io && docker load -i
{artifacts:path}/hello-world.tar
• The system user that runs a Docker container component must have root or administrator permissions,
or you must configure Docker to run it as a non-root or non-admistrator user. On Linux devices, you
can add a user to the docker group to call docker commands without sudo. On Windows devices,
you can add a user to the docker-users group to call docker commands without adminstrator
privileges.
On Linux, to add ggc_user, or the non-root user that you use to run AWS IoT Greengrass, to the
docker group that you configure, run the following command.
sudo usermod -aG docker user-name
For more information, see the following Docker documentation:
• Linux: Manage Docker as a non-root user
457
AWS IoT Greengrass Developer Guide, Version 2
Requirements
• Windows: Install Docker Desktop on Windows
• Files accessed by the Docker container component mounted as a volume in the Docker container.
• If you configure the AWS IoT Greengrass Core software to use a network proxy (p. 165), you must
configure Docker to use the same proxy server.
In addition to these requirements, you must also meet the following requirements if they apply to your
environment:
• To use Docker Compose to create and start your Docker containers, install Docker Compose on your
Greengrass core device, and upload your Docker Compose file to an S3 bucket. You must store your
Compose file in an S3 bucket in the same AWS account and AWS Region as the component. For an
example that uses the docker-compose up command in a custom component, see Run a Docker
container from a public image in Amazon ECR or Docker Hub (p. 459).
• If you run AWS IoT Greengrass behind a network proxy, configure the Docker daemon to use a proxy
server.
• If your Docker images are stored in Amazon ECR or Docker Hub, include the Docker component
manager (p. 216) component as a dependency in your Docker container component. You must start
the Docker daemon on the core device before you deploy your component.
Also, include the image URIs as component artifacts. Image URIs must be in the format
docker:registry/image[:tag|@digest] as shown in the following examples:
• Private Amazon ECR image: docker:account-
id.dkr.ecr.region.amazonaws.com/repository/image[:tag|@digest]
• Public Amazon ECR image: docker:public.ecr.aws/repository/image[:tag|@digest]
• Public Docker Hub image: docker:name[:tag|@digest]
For more information about running Docker containers from images stored in public repositories, see
Run a Docker container from a public image in Amazon ECR or Docker Hub (p. 459).
• If your Docker images are stored in an Amazon ECR private repository, then you must include
the token exchange service component as a dependency in the Docker container component.
Also, the Greengrass device role (p. 790) must allow the ecr:GetAuthorizationToken,
ecr:BatchGetImage, and ecr:GetDownloadUrlForLayer actions, as shown in the following
example IAM policy.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"ecr:GetAuthorizationToken",
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer"
],
"Resource": [
"*"
],
"Effect": "Allow"
}
]
}
For information about running Docker containers from images stored in an Amazon ECR private
repository, see Run a Docker container from a private image in Amazon ECR (p. 461).
• If your Docker images or Compose files are stored in an S3 bucket, the Greengrass device
role (p. 790) must allow the s3:GetObject permission to allow core devices to download the
images as component artifacts, as shown in the following example IAM policy.
458
AWS IoT Greengrass Developer Guide, Version 2
Run a Docker container from a public
image in Amazon ECR or Docker Hub
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"s3:GetObject"
],
"Resource": [
"*"
],
"Effect": "Allow"
}
]
}
For information about running Docker containers from images stored in Amazon S3, see Run a Docker
container from an image in Amazon S3 (p. 463).
• To use interprocess communication (IPC), AWS credentials, or stream manager in your Docker
container component, you must specify additional options when you run the Docker container. For
more information, see the following:
• Use interprocess communication in Docker container components (p. 465)
• Use AWS credentials in Docker container components (Linux) (p. 467)
• Use stream manager in Docker container components (Linux) (p. 469)
Run a Docker container from a public image in
Amazon ECR or Docker Hub
This section describes how you can create a custom component that uses Docker Compose to run a
Docker container from Docker images that are stored Amazon ECR and Docker Hub.
To run a Docker container using Docker Compose
1. Create and upload a Docker Compose file to an Amazon S3 bucket. Make sure that the Greengrass
device role (p. 790) allows the s3:GetObject permission to enable the device to access the
Compose file. The example Compose file shown in the following example includes the Amazon
CloudWatch Agent image from Amazon ECR and the MySQL image from Docker Hub.
version: "3"
services:
cloudwatchagent:
image: "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest"
mysql:
image: "mysql:8.0"
2. Create a custom component (p. 442) on your AWS IoT Greengrass core device. The example recipe
shown in the following example has the following properties:
• The Docker application manager component as a dependency. This component enables AWS IoT
Greengrass to download images from public Amazon ECR and Docker Hub repositories.
• A component artifact that specifies a Docker image in a public Amazon ECR repository.
• A component artifact that specifies a Docker image in a public Docker Hub repository.
• A component artifact that specifies the Docker Compose file that includes containers for the
Docker images that you want to run.
459
AWS IoT Greengrass Developer Guide, Version 2
Run a Docker container from a public
image in Amazon ECR or Docker Hub
• A lifecycle run script that uses docker-compose up to create and start a container from the
specified images.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.MyDockerComposeComponent",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that uses Docker Compose to run images from
public Amazon ECR and Docker Hub.",
"ComponentPublisher": "Amazon",
"ComponentDependencies": {
"aws.greengrass.DockerApplicationManager": {
"VersionRequirement": "~2.0.0"
}
},
"Manifests": [
{
"Platform": {
"os": "all"
},
"Lifecycle": {
"Run": "docker-compose -f {artifacts:path}/docker-compose.yaml up"
},
"Artifacts": [
{
"URI": "docker:public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest"
},
{
"URI": "docker:mysql:8.0"
},
{
"URI": "s3://DOC-EXAMPLE-BUCKET/folder/docker-compose.yaml"
}
]
}
]
}
YAML
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.MyDockerComposeComponent
ComponentVersion: '1.0.0'
ComponentDescription: 'A component that uses Docker Compose to run images from
public Amazon ECR and Docker Hub.'
ComponentPublisher: Amazon
ComponentDependencies:
aws.greengrass.DockerApplicationManager:
VersionRequirement: ~2.0.0
Manifests:
- Platform:
os: all
Lifecycle:
Run: docker-compose -f {artifacts:path}/docker-compose.yaml up
Artifacts:
- URI: "docker:public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest"
- URI: "docker:mysql:8.0"
- URI: "s3://DOC-EXAMPLE-BUCKET/folder/docker-compose.yaml"
460
AWS IoT Greengrass Developer Guide, Version 2
Run a Docker container from a
private image in Amazon ECR
Note
To use interprocess communication (IPC), AWS credentials, or stream manager in your
Docker container component, you must specify additional options when you run the Docker
container. For more information, see the following:
• Use interprocess communication in Docker container components (p. 465)
• Use AWS credentials in Docker container components (Linux) (p. 467)
• Use stream manager in Docker container components (Linux) (p. 469)
3. Test the component (p. 449) to verify that it works as expected.
Important
You must install and start the Docker daemon before you deploy the component.
After you deploy the component locally, you can run the docker container ls command to verify that
your container runs.
docker container ls
4. When the component is ready, upload the component to AWS IoT Greengrass to deploy to
other core devices. For more information, see Publish components to deploy to your core
devices (p. 451).
Run a Docker container from a private image in
Amazon ECR
This section describes how you can create a custom component that runs a Docker container from a
Docker image that is stored in a private repository in Amazon ECR.
To run a Docker container
1. Create a custom component (p. 442) on your AWS IoT Greengrass core device. Use the following
example recipe, which has the following properties:
• The Docker application manager component as a dependency. This component enables AWS IoT
Greengrass to manage credentials to download images from private repositories.
• The token exchange service component as a dependency. This component enables AWS IoT
Greengrass to retrieve AWS credentials to interact with Amazon ECR.
• A component artifact that specifies a Docker image in a private Amazon ECR repository.
• A lifecycle run script that uses docker run to create and start a container from the image.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.MyPrivateDockerComponent",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that runs a Docker container from a private
Amazon ECR image.",
"ComponentPublisher": "Amazon",
"ComponentDependencies": {
"aws.greengrass.DockerApplicationManager": {
"VersionRequirement": "~2.0.0"
},
461
AWS IoT Greengrass Developer Guide, Version 2
Run a Docker container from a
private image in Amazon ECR
"aws.greengrass.TokenExchangeService": {
"VersionRequirement": "~2.0.0"
}
},
"Manifests": [
{
"Platform": {
"os": "all"
},
"Lifecycle": {
"Run": "docker run account-id.dkr.ecr.region.amazonaws.com/repository[:tag|
@digest]"
},
"Artifacts": [
{
"URI": "docker:account-id.dkr.ecr.region.amazonaws.com/repository[:tag|
@digest]"
}
]
}
]
}
YAML
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.MyPrivateDockerComponent
ComponentVersion: '1.0.0'
ComponentDescription: 'A component that runs a Docker container from a private
Amazon ECR image.'
ComponentPublisher: Amazon
ComponentDependencies:
aws.greengrass.DockerApplicationManager:
VersionRequirement: ~2.0.0
aws.greengrass.TokenExchangeService:
VersionRequirement: ~2.0.0
Manifests:
- Platform:
os: all
Lifecycle:
Run: docker run account-id.dkr.ecr.region.amazonaws.com/repository[:tag|
@digest]
Artifacts:
- URI: "docker:account-id.dkr.ecr.region.amazonaws.com/repository[:tag|
@digest]"
Note
To use interprocess communication (IPC), AWS credentials, or stream manager in your
Docker container component, you must specify additional options when you run the Docker
container. For more information, see the following:
• Use interprocess communication in Docker container components (p. 465)
• Use AWS credentials in Docker container components (Linux) (p. 467)
• Use stream manager in Docker container components (Linux) (p. 469)
2. Test the component (p. 449) to verify that it works as expected.
Important
You must install and start the Docker daemon before you deploy the component.
462
AWS IoT Greengrass Developer Guide, Version 2
Run a Docker container from an image in Amazon S3
After you deploy the component locally, you can run the docker container ls command to verify that
your container runs.
docker container ls
3. Upload the component to AWS IoT Greengrass to deploy to other core devices. For more
information, see Publish components to deploy to your core devices (p. 451).
Run a Docker container from an image in Amazon S3
This section describes how you can run a Docker container in a component from a Docker image that is
stored in Amazon S3.
To run a Docker container in a component from an image in Amazon S3
1. Run the docker save command to create a backup of a Docker container. You provide this backup as
a component artifact to run the container on AWS IoT Greengrass. Replace hello-world with the
name of the image, and replace hello-world.tar with the name of the archive file to create.
docker save hello-world > artifacts/com.example.MyDockerComponent/1.0.0/hello-world.tar
2. Create a custom component (p. 442) on your AWS IoT Greengrass core device. Use the following
example recipe, which has the following properties:
• A lifecycle install script that uses docker load to load a Docker image from an archive.
• A lifecycle run script that uses docker run to create and start a container from the image. The --
rm option cleans up the container when it exits.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.MyS3DockerComponent",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that runs a Docker container from an image
in an S3 bucket.",
"ComponentPublisher": "Amazon",
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"Install": {
"Script": "docker load -i {artifacts:path}/hello-world.tar"
},
"Run": {
"Script": "docker run --rm hello-world"
}
}
}
]
}
YAML
---
463
AWS IoT Greengrass Developer Guide, Version 2
Run a Docker container from an image in Amazon S3
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.MyS3DockerComponent
ComponentVersion: '1.0.0'
ComponentDescription: 'A component that runs a Docker container from an image in an
S3 bucket.'
ComponentPublisher: Amazon
Manifests:
- Platform:
os: linux
Lifecycle:
Install:
Script: docker load -i {artifacts:path}/hello-world.tar
Run:
Script: docker run --rm hello-world
Note
To use interprocess communication (IPC), AWS credentials, or stream manager in your
Docker container component, you must specify additional options when you run the Docker
container. For more information, see the following:
• Use interprocess communication in Docker container components (p. 465)
• Use AWS credentials in Docker container components (Linux) (p. 467)
• Use stream manager in Docker container components (Linux) (p. 469)
3. Test the component (p. 449) to verify that it works as expected.
After you deploy the component locally, you can run the docker container ls command to verify that
your container runs.
docker container ls
4. When the component is ready, upload the Docker image archive to an S3 bucket, and add its
URI to the component recipe. Then, you can upload the component to AWS IoT Greengrass to
deploy to other core devices. For more information, see Publish components to deploy to your core
devices (p. 451).
When you're done, the component recipe should look like the following example.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.MyS3DockerComponent",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that runs a Docker container from an image
in an S3 bucket.",
"ComponentPublisher": "Amazon",
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"Install": {
"Script": "docker load -i {artifacts:path}/hello-world.tar"
},
"Run": {
"Script": "docker run --rm hello-world"
}
},
"Artifacts": [
464
AWS IoT Greengrass Developer Guide, Version 2
Use interprocess communication
in Docker container components
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.MyDockerComponent/1.0.0/hello-world.tar"
}
]
}
]
}
YAML
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.MyS3DockerComponent
ComponentVersion: '1.0.0'
ComponentDescription: 'A component that runs a Docker container from an image in an
S3 bucket.'
ComponentPublisher: Amazon
Manifests:
- Platform:
os: linux
Lifecycle:
Install:
Script: docker load -i {artifacts:path}/hello-world.tar
Run:
Script: docker run --rm hello-world
Artifacts:
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.MyDockerComponent/1.0.0/
hello-world.tar
Use interprocess communication in Docker container
components
You can use the Greengrass interprocess communication (IPC) library in the AWS IoT Device SDK to
communicate with the Greengrass nucleus, other Greengrass components, and AWS IoT Core. For more
information, see Use the AWS IoT Device SDK to communicate with the Greengrass nucleus, other
components, and AWS IoT Core (p. 545).
To use IPC in a Docker container component, you must run the Docker container with the following
parameters:
• Mount the IPC socket in the container. The Greengrass nucleus provides the IPC socket file path in the
AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT environment variable.
• Set the SVCUID and AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT environment
variables to the values that the Greengrass nucleus provides to components. Your component uses
these environment variables to authenticate connections to the Greengrass nucleus.
Example Example recipe: Publish an MQTT message to AWS IoT Core (Python)
The following recipe defines an example Docker container component that publishes an MQTT message
to AWS IoT Core. This recipe has the following properties:
• An authorization policy (accessControl) that allows the component to publish MQTT messages
to AWS IoT Core on all topics. For more information, see Authorize components to perform IPC
operations (p. 552) and AWS IoT Core MQTT IPC authorization (p. 586).
• A component artifact that specifies a Docker image as a TAR archive in Amazon S3.
465
AWS IoT Greengrass Developer Guide, Version 2
Use interprocess communication
in Docker container components
• A lifecycle install script that loads the Docker image from the TAR archive.
• A lifecycle run script that runs a Docker container from the image. The Docker run command has the
following arguments:
• The -v argument mounts the Greengrass IPC socket in the container.
• The first two -e arguments set the required environment variables in the Docker container.
• The additional -e arguments set environment variables used by this example.
• The --rm argument cleans up the container when it exits.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.python.docker.PublishToIoTCore",
"ComponentVersion": "1.0.0",
"ComponentDescription": "Uses interprocess communication to publish an MQTT message
to IoT Core.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"topic": "test/topic/java",
"message": "Hello, World!",
"qos": "1",
"accessControl": {
"aws.greengrass.ipc.mqttproxy": {
"com.example.python.docker.PublishToIoTCore:pubsub:1": {
"policyDescription": "Allows access to publish to IoT Core on all topics.",
"operations": [
"aws.greengrass#PublishToIoTCore"
],
"resources": [
"*"
]
}
}
}
}
},
"Manifests": [
{
"Platform": {
"os": "all"
},
"Lifecycle": {
"Install": "docker load -i {artifacts:path}/publish-to-iot-core.tar",
"Run": "docker run -v $AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT:
$AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT -e SVCUID -e
AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT -e MQTT_TOPIC=\"{configuration:/
topic}\" -e MQTT_MESSAGE=\"{configuration:/message}\" -e MQTT_QOS=\"{configuration:/
qos}\" --rm publish-to-iot-core"
},
"Artifacts": [
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.python.docker.PublishToIoTCore/1.0.0/publish-to-iot-core.tar"
}
]
}
]
}
466
AWS IoT Greengrass Developer Guide, Version 2
Use AWS credentials in Docker
container components (Linux)
YAML
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.python.docker.PublishToIoTCore
ComponentVersion: 1.0.0
ComponentDescription: Uses interprocess communication to publish an MQTT message to IoT
Core.
ComponentPublisher: Amazon
ComponentConfiguration:
DefaultConfiguration:
topic: 'test/topic/java'
message: 'Hello, World!'
qos: '1'
accessControl:
aws.greengrass.ipc.mqttproxy:
'com.example.python.docker.PublishToIoTCore:pubsub:1':
policyDescription: Allows access to publish to IoT Core on all topics.
operations:
- 'aws.greengrass#PublishToIoTCore'
resources:
- '*'
Manifests:
- Platform:
os: all
Lifecycle:
Install: 'docker load -i {artifacts:path}/publish-to-iot-core.tar'
Run: |
docker run \
-v $AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT:
$AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT \
-e SVCUID \
-e AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT \
-e MQTT_TOPIC="{configuration:/topic}" \
-e MQTT_MESSAGE="{configuration:/message}" \
-e MQTT_QOS="{configuration:/qos}" \
--rm publish-to-iot-core
Artifacts:
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.python.docker.PublishToIoTCore/1.0.0/publish-to-iot-core.tar
Use AWS credentials in Docker container components
(Linux)
You can use the token exchange service component (p. 407) to interact with AWS services in
Greengrass components. This component provides AWS credentials from the core device's token
exchange role (p. 790) using a local container server. For more information, see Interact with AWS
services (p. 454).
Note
The example in this section works only on Linux core devices.
To use AWS credentials from the token exchange service in a Docker container component, you must run
the Docker container with the following parameters:
• Provide access to the host network using the --network=host argument. This option enables the
Docker container to connect to the local token exchange service to retrieve AWS credentials. This
argument works on only Docker for Linux.
467
AWS IoT Greengrass Developer Guide, Version 2
Use AWS credentials in Docker
container components (Linux)
Warning
This option gives the container access to all local network interfaces on the host, so this
option is less secure than if you run Docker containers without this access to the host network.
Consider this when you develop and run Docker container components that use this option.
For more information, see Network: host in the Docker Documentation.
• Set the AWS_CONTAINER_CREDENTIALS_FULL_URI and AWS_CONTAINER_AUTHORIZATION_TOKEN
environment variables to the values that the Greengrass nucleus provides to components. AWS SDKs
use these environment variables to retrieve AWS credentials.
Example Example recipe: List S3 buckets in a Docker container component (Python)
The following recipe defines an example Docker container component that lists the S3 buckets in your
AWS account. This recipe has the following properties:
• The token exchange service component as a dependency. This dependency enables the component to
retrieve AWS credentials to interact with other AWS services.
• A component artifact that specifies a Docker image as a tar archive in Amazon S3.
• A lifecycle install script that loads the Docker image from the TAR archive.
• A lifecycle run script that runs a Docker container from the image. The Docker run command has the
following arguments:
• The --network=host argument provides the container access to the host network, so the container
can connect to the token exchange service.
• The -e argument sets the required environment variables in the Docker container.
• The --rm argument cleans up the container when it exits.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.python.docker.ListS3Buckets",
"ComponentVersion": "1.0.0",
"ComponentDescription": "Uses the token exchange service to lists your S3 buckets.",
"ComponentPublisher": "Amazon",
"ComponentDependencies": {
"aws.greengrass.TokenExchangeService": {
"VersionRequirement": "^2.0.0",
"DependencyType": "HARD"
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"Install": "docker load -i {artifacts:path}/list-s3-buckets.tar",
"Run": "docker run --network=host -e AWS_CONTAINER_AUTHORIZATION_TOKEN -e
AWS_CONTAINER_CREDENTIALS_FULL_URI --rm list-s3-buckets"
},
"Artifacts": [
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.python.docker.ListS3Buckets/1.0.0/list-s3-buckets.tar"
}
]
}
]
468
AWS IoT Greengrass Developer Guide, Version 2
Use stream manager in Docker
container components (Linux)
YAML
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.python.docker.ListS3Buckets
ComponentVersion: 1.0.0
ComponentDescription: Uses the token exchange service to lists your S3 buckets.
ComponentPublisher: Amazon
ComponentDependencies:
aws.greengrass.TokenExchangeService:
VersionRequirement: ^2.0.0
DependencyType: HARD
Manifests:
- Platform:
os: linux
Lifecycle:
Install: 'docker load -i {artifacts:path}/list-s3-buckets.tar'
Run: |
docker run \
--network=host \
-e AWS_CONTAINER_AUTHORIZATION_TOKEN \
-e AWS_CONTAINER_CREDENTIALS_FULL_URI \
--rm list-s3-buckets
Artifacts:
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.python.docker.ListS3Buckets/1.0.0/list-s3-buckets.tar
Use stream manager in Docker container components
(Linux)
You can use the stream manager component (p. 398) to manage data streams in Greengrass
components. This component enables you to process data streams and transfer high-volume IoT data
to the AWS Cloud. AWS IoT Greengrass provides a stream manager SDK that you use to interact with
the stream manager component. For more information, see Manage data streams on the AWS IoT
Greengrass Core (p. 682).
Note
The example in this section works only on Linux core devices.
To use the stream manager SDK in a Docker container component, you must run the Docker container
with the following parameters:
• Provide access to the host network using the --network=host argument. This option enables the
Docker container to interact with the stream manager component over a local TLS connection. This
argument works on only Docker for Linux
Warning
This option gives the container access to all local network interfaces on the host, so this
option is less secure than if you run Docker containers without this access to the host network.
Consider this when you develop and run Docker container components that use this option.
For more information, see Network: host in the Docker Documentation.
• If you configure the stream manager component to require authentication, which is the default
behavior, set the AWS_CONTAINER_CREDENTIALS_FULL_URI environment variable to the value
that the Greengrass nucleus provides to components. For more information, see stream manager
configuration (p. 401).
• If you configure the stream manager component to use a non-default port, use interprocess
communication (IPC) (p. 545) to get the port from the stream manager component configuration.
469
AWS IoT Greengrass Developer Guide, Version 2
Use stream manager in Docker
container components (Linux)
You must run the Docker container with additional options to use IPC. For more information, see the
following:
• Connect to stream manager in application code (p. 693)
• Use interprocess communication in Docker container components (p. 465)
Example Example recipe: Stream a file to an S3 bucket in a Docker container component
(Python)
The following recipe defines an example Docker container component that creates a file and streams it
to an S3 bucket. This recipe has the following properties:
• The stream manager component as a dependency. This dependency enables the component to use the
stream manager SDK to interact with the stream manager component.
• A component artifact that specifies a Docker image as a TAR archive in Amazon S3.
• A lifecycle install script that loads the Docker image from the TAR archive.
• A lifecycle run script that runs a Docker container from the image. The Docker run command has the
following arguments:
• The --network=host argument provides the container access to the host network, so the container
can connect to the stream manager component.
• The first -e argument sets the required AWS_CONTAINER_CREDENTIALS_FULL_URI environment
variable in the Docker container.
• The additional -e arguments set environment variables used by this example.
• The -v argument mounts the component's work folder (p. 485) in the container. This example
creates a file in the work folder to upload that file to Amazon S3 using stream manager.
• The --rm argument cleans up the container when it exits.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.python.docker.StreamFileToS3",
"ComponentVersion": "1.0.0",
"ComponentDescription": "Creates a text file and uses stream manager to stream the
file to S3.",
"ComponentPublisher": "Amazon",
"ComponentDependencies": {
"aws.greengrass.StreamManager": {
"VersionRequirement": "^2.0.0",
"DependencyType": "HARD"
}
},
"ComponentConfiguration": {
"DefaultConfiguration": {
"bucketName": ""
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"Install": "docker load -i {artifacts:path}/stream-file-to-s3.tar",
"Run": "docker run --network=host -e AWS_CONTAINER_AUTHORIZATION_TOKEN
-e BUCKET_NAME=\"{configuration:/bucketName}\" -e WORK_PATH=\"{work:path}\" -v
{work:path}:{work:path} --rm stream-file-to-s3"
},
470
AWS IoT Greengrass Developer Guide, Version 2
Recipe reference
"Artifacts": [
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.python.docker.StreamFileToS3/1.0.0/stream-file-to-s3.tar"
}
]
}
]
}
YAML
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.python.docker.StreamFileToS3
ComponentVersion: 1.0.0
ComponentDescription: Creates a text file and uses stream manager to stream the file to
S3.
ComponentPublisher: Amazon
ComponentDependencies:
aws.greengrass.StreamManager:
VersionRequirement: ^2.0.0
DependencyType: HARD
ComponentConfiguration:
DefaultConfiguration:
bucketName: ''
Manifests:
- Platform:
os: linux
Lifecycle:
Install: 'docker load -i {artifacts:path}/stream-file-to-s3.tar'
Run: |
docker run \
--network=host \
-e AWS_CONTAINER_AUTHORIZATION_TOKEN \
-e BUCKET_NAME="{configuration:/bucketName}" \
-e WORK_PATH="{work:path}" \
-v {work:path}:{work:path} \
--rm stream-file-to-s3
Artifacts:
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.python.docker.StreamFileToS3/1.0.0/stream-file-to-s3.tar
AWS IoT Greengrass component recipe reference
The component recipe is a file that defines a component's details, dependencies, artifacts, and lifecycles.
The component lifecycle specifies the commands to run to install, run, and shut down the component,
for example. The AWS IoT Greengrass core uses the lifecycles that you define in the recipe to install
and run components. The AWS IoT Greengrass service uses the recipe to identify the dependencies and
artifacts to deploy to your core devices when you deploy the component.
In the recipe, you can define unique dependencies and lifecycles for each platform that a component
supports. You can use this capability to deploy a component to devices with multiple platforms that have
different requirements. You can also use this to prevent AWS IoT Greengrass from installing a component
on devices that don't support it.
Each recipe contains a list of manifests. Each manifest specifies a set of platform requirements and the
lifecycle and artifacts to use for core devices whose platform meets those requirements. The core device
uses the first manifest with platform requirements that the device meets. Specify a manifest without any
platform requirements to match any core device.
471
AWS IoT Greengrass Developer Guide, Version 2
Recipe format
You can also specify a global lifecycle that isn't in a manifest. In the global lifecycle, you can use selection
keys that identify sub-sections of the lifecycle. Then, you can specify these selection keys within a
manifest to use those sections of the global lifecycle in addition to the manifest's lifecycle. The core
device uses the manifest's selection keys only if the manifest doesn't define a lifecycle. You can use the
all selection in a manifest to match sections of the global lifecycle without selection keys.
After the AWS IoT Greengrass Core software selects a manifest that matches the core device, it does the
following to identify the lifecycle steps to use:
• If the selected manifest defines a lifecycle, the core device uses that lifecycle.
• If the selected manifest doesn't define a lifecycle, the core device uses the global lifecycle. The core
device does the following to identify which sections of the global lifecycle to use:
• If the manifest defines selection keys, the core device uses the sections of the global lifecycle that
contain the manifest's selection keys.
• If the manifest doesn't define selection keys, the core device uses the sections of the global lifecycle
that don't have selection keys. This behavior is equivalent to a manifest that defines the all
selection.
Important
A core device must match least one manifest's platform requirements to install the component.
If no manifest matches the core device, then the AWS IoT Greengrass Core software doesn't
install the component and the deployment fails.
You can define recipes in JSON or YAML format. The recipe examples section includes recipes in each
format.
Topics
• Recipe format (p. 472)
• Recipe variables (p. 484)
• Recipe examples (p. 485)
Recipe format
When you define a recipe for a component, you specify the following information in the recipe
document. The same structure applies to recipes in YAML and JSON formats.
RecipeFormatVersion
The template version for the recipe. Choose the following option:
• 2020-01-25
ComponentName
The name of the component that this recipe defines. The component name must be unique in your
AWS account in each Region.
Tips
• Use inverse domain name format to avoid name collision within your company. For
example, if your company owns example.com and you work on a solar energy project,
you can name your Hello World component com.example.solar.HelloWorld. This
helps avoid component name collisions within your company.
• Avoid the aws.greengrass prefix in your component names. AWS IoT Greengrass uses
this prefix for the public components (p. 175) that it provides. If you choose the same
name as a public component, your component replaces that component. Then, AWS IoT
Greengrass provides your component instead of the public component when it deploys
472
AWS IoT Greengrass Developer Guide, Version 2
Recipe format
components with a dependency on that public component. This feature enables you to
override the behavior of public components, but it can also break other components if
you don't intend to override a public component.
ComponentVersion
The version of the component.
Note
AWS IoT Greengrass uses semantic versions for components. Semantic versions follow a
major.minor.patch number system. For example, version 1.0.0 represents the first major
release for a component. For more information, see the semantic version specification.
ComponentDescription
(Optional) The description of the component.
ComponentPublisher
The publisher or author of the component.
ComponentConfiguration
(Optional) An object that defines the configuration or parameters for the component. You define the
default configuration, and then when you deploy the component, you can specify the configuration
object to provide to the component. Component configuration supports nested parameters and
structures. This object contains the following information:
DefaultConfiguration
An object that defines the default configuration for the component. You define the structure of
this object.
Note
AWS IoT Greengrass uses JSON for configuration values. JSON specifies a number type
but doesn't differentiate between integers and floats. As a result, configuration values
might convert to floats in AWS IoT Greengrass. To ensure that your component uses
the correct data type, we recommend that you define numeric configuration values as
strings. Then, have your component parse them as integers or floats. This ensures that
your configuration values have the same type in the configuration and on your core
device.
ComponentDependencies
(Optional) A dictionary of objects that each define a component dependency for the component.
The key for each object identifies the name of the component dependency. AWS IoT Greengrass
installs component dependencies when the component installs. AWS IoT Greengrass waits
for dependencies to start before it starts the component. Each object contains the following
information:
VersionRequirement
The npm-style semantic version constraint that defines the compatible component versions for
this dependency. You can specify a version or a range of versions. For more information, see the
npm semantic version calculator.
DependencyType
(Optional) The type of this dependency. Choose from the following options.
• SOFT – The component doesn't restart if the dependency changes state.
• HARD – The component restarts if the dependency changes state.
Defaults to HARD.
ComponentType
(Optional) The type of component.
473
AWS IoT Greengrass Developer Guide, Version 2
Recipe format
Note
We don't recommend that you specify the component type in a recipe. AWS IoT Greengrass
sets the type for you when you create a component.
The type can be one the following types:
• aws.greengrass.generic – The component runs commands or provides artifacts.
• aws.greengrass.lambda – The component runs a Lambda function using the Lambda launcher
component (p. 252). The ComponentSource parameter specifies the ARN of the Lambda function
that this component runs.
We don't recommend that you use this option, because it's set by AWS IoT Greengrass when
you create a component from a Lambda function. For more information, see Run AWS Lambda
functions (p. 523).
• aws.greengrass.plugin – The component runs in the same Java Virtual Machine (JVM) as the
Greengrass nucleus. If you deploy or restart a plugin component, the Greengrass nucleus restarts.
Plugin components use the same log file as the Greengrass nucleus. For more information, see
Monitor AWS IoT Greengrass logs (p. 506).
We don't recommend that you use this option in component recipes, because it's intended
for AWS-provided components written in Java that directly interface with the Greengrass
nucleus. For more information about which public components are plugins, see AWS-provided
components (p. 175).
• aws.greengrass.nucleus – The nucleus component. For more information, see Greengrass
nucleus (p. 181).
We don't recommend that you use this option in component recipes. It is intended for the
Greengrass nucleus component, which provides the minimum functionality of the AWS IoT
Greengrass Core software.
Defaults to aws.greengrass.generic when you create a component from a recipe, or
aws.greengrass.lambda when you create a component from a Lambda function.
For more information, see Component types (p. 441).
ComponentSource
(Optional) The ARN of the Lambda function that a component runs.
We don't recommend that you specify the component source in a recipe. AWS IoT Greengrass
sets this parameter for you when you create a component from a Lambda function. For more
information, see Run AWS Lambda functions (p. 523).
Manifests
A list of objects that each define the component's lifecycle, parameters, and requirements for a
platform. If a core device matches multiple manifests' platform requirements, AWS IoT Greengrass
uses the first manifest that the core device matches. To ensure that core devices use the correct
manifest, define the manifests with stricter platform requirements first. A manifest that applies to
all platforms must be the last manifest in the list.
Important
A core device must match least one manifest's platform requirements to install the
component. If no manifest matches the core device, then the AWS IoT Greengrass Core
software doesn't install the component and the deployment fails.
Each object contains the following information:
Name
(Optional) A friendly name for the platform that this manifest defines.
474
AWS IoT Greengrass Developer Guide, Version 2
Recipe format
If you omit this parameter, AWS IoT Greengrass creates a name from the platform os and
architecture.
Platform
(Optional) An object that defines the platform to which this manifest applies. Omit this
parameter to define a manifest that applies to all platforms.
This object specifies key-value pairs about the platform on which a core device runs. When
you deploy this component, the AWS IoT Greengrass Core software compares these key-
value pairs with the platform attributes on the core device. The AWS IoT Greengrass Core
software always defines os and architecture, and it might define additional attributes.
You can specify custom platform attributes for a core device when you deploy the Greengrass
nucleus component. For more information, see the platform overrides parameter (p. 188) of the
Greengrass nucleus component (p. 181).
For each key-value pair, you can specify one of the following values:
• An exact value, such as linux or windows. Exact values must start with a letter or a number.
• *, which matches any value. This also matches when a value isn't present.
• A Java-style regular expression, such as /windows|linux/. The regular expression must start
and end with a slash character (/). For example, the regular expression /.+/ matches any
non-blank value.
This object contains the following information:
os
(Optional) The name of the operating system for the platform that this manifest supports.
Common platforms include the following values:
• linux
• windows
• darwin (macOS)
architecture
(Optional) The processor architecture for the platform that this manifest supports. Common
architectures include the following values:
• amd64
• arm
• aarch64
• x86
key
(Optional) A platform attribute that you define for this manifest. Replace key with
the name of the platform attribute. The AWS IoT Greengrass Core software matches
this platform attribute with the key-value pairs that you specify in the Greengrass
nucleus component configuration. For more information, see the platform overrides
parameter (p. 188) of the Greengrass nucleus component (p. 181).
Tip
Use inverse domain name format to avoid name collision within your company. For
example, if your company owns example.com and you work on a radio project,
you can name a custom platform attribute com.example.radio.RadioModule.
This helps avoid platform attribute name collisions within your company.
For example, you might define a platform attribute, com.example.radio.RadioModule,
to specify a different manifest based on which radio module is available on a core
device. Each manifest can include different artifacts that apply to different hardware
configurations, so that you deploy the minimal set of software to the core device.
475
AWS IoT Greengrass Developer Guide, Version 2
Recipe format
Lifecycle
An object that defines how to install and run the component on the platform that this manifest
defines. You can also define a global lifecycle (p. 482) that applies to all platforms. The core
device uses the global lifecycle only if the manifest to use doesn't specify a lifecycle.
Note
You define this lifecycle within a manifest. The lifecycle steps that you specify here
apply to only the platform that this manifest defines. You can also define a global
lifecycle (p. 482) that applies to all platforms.
This object contains the following information:
Setenv
(Optional) A dictionary of environment variables to provide to all lifecycle scripts. You can
override these environment variables with Setenv in each lifecycle script.
Bootstrap
(Optional) An object that defines the script to run when the AWS IoT Greengrass Core
software deploys the component. This lifecycle step runs before the install lifecycle
step (p. 477) in the following cases:
• The component deploys to the core device for the first time.
• The component version changes.
• The bootstrap script changes as the result of a component configuration update.
You can use this lifecycle step to restart the AWS IoT Greengrass Core software or restart
the core device. This lets you develop a component that performs a restart after it installs
operating system updates or runtime updates, for example.
After the AWS IoT Greengrass Core software completes the bootstrap step for all
components that have a bootstrap step in a deployment, the software restarts.
Important
You must configure the AWS IoT Greengrass Core software as a system service
to restart the AWS IoT Greengrass Core software or the core device. If you don't
configure the AWS IoT Greengrass Core software as a system service, the software
won't restart. For more information, see Configure the Greengrass nucleus as a
system service (p. 158).
This object contains the following information:
Script
The script to run. The exit code of this script defines the restart instruction. Use the
following exit codes:
• 0 – Don't restart the AWS IoT Greengrass Core software or the core device. The AWS
IoT Greengrass Core software still restarts after all components bootstrap.
• 100 – Request to restart the AWS IoT Greengrass Core software.
• 101 – Request to restart the core device.
Exit codes 100 to 199 are reserved for special behavior. Other exit codes represent
script errors.
RequiresPrivilege
(Optional) You can run the script with root privileges. If you set this option to true,
then the AWS IoT Greengrass Core software runs this lifecycle script as root instead of
as the system user that you configure to run this component. Defaults to false.
476
AWS IoT Greengrass Developer Guide, Version 2
Recipe format
Timeout
(Optional) The maximum amount of time in seconds that the script can run before the
AWS IoT Greengrass Core software terminates the process.
Default: 120 seconds
Setenv
(Optional) The dictionary of environment variables to provide to the script. These
environment variables override the variables that you provide in Lifecycle.Setenv.
Install
(Optional) An object that defines the script to run when the component installs. The AWS
IoT Greengrass Core software also runs this lifecycle step when each time the software
launches.
If the Install script exits with a success code, the component enters the INSTALLED state.
This object contains the following information:
Script
The script to run.
RequiresPrivilege
(Optional) You can run the script with root privileges. If you set this option to true,
then the AWS IoT Greengrass Core software runs this lifecycle script as root instead of
as the system user that you configure to run this component. Defaults to false.
Skipif
(Optional) The check to determine whether or not to run the script. You can define to
check if an executable is on the path or if a file exists. If the output is true, then the
AWS IoT Greengrass Core software skips the step. Choose from the following checks:
• onpath runnable – Check if a runnable is on the system path. For example, use
onpath python3 to skip this lifecycle step if Python 3 is available.
• exists file – Check if a file exists. For example, use exists /tmp/my-
configuration.db to skip this lifecycle step if /tmp/my-configuration.db is
present.
Timeout
(Optional) The maximum amount of time in seconds that the script can run before the
AWS IoT Greengrass Core software terminates the process.
Default: 120 seconds
Setenv
(Optional) The dictionary of environment variables to provide to the script. These
environment variables override the variables that you provide in Lifecycle.Setenv.
Run
(Optional) An object that defines the script to run when the component starts.
The component enters the RUNNING state when this lifecycle step runs. If the Run script
exits with a success code, the component enters the FINISHED state.
Components that depend on this component start when this lifecycle step runs. To run a
background process, such as a service that dependent components use, use the Startup
lifecycle step instead.
477
AWS IoT Greengrass Developer Guide, Version 2
Recipe format
Note
You can define only one Startup or Run lifecycle.
This object contains the following information:
Script
The script to run.
RequiresPrivilege
(Optional) You can run the script with root privileges. If you set this option to true,
then the AWS IoT Greengrass Core software runs this lifecycle script as root instead of
as the system user that you configure to run this component. Defaults to false.
Skipif
(Optional) The check to determine whether or not to run the script. You can define to
check if an executable is on the path or if a file exists. If the output is true, then the
AWS IoT Greengrass Core software skips the step. Choose from the following checks:
• onpath runnable – Check if a runnable is on the system path. For example, use
onpath python3 to skip this lifecycle step if Python 3 is available.
• exists file – Check if a file exists. For example, use exists /tmp/my-
configuration.db to skip this lifecycle step if /tmp/my-configuration.db is
present.
Timeout
(Optional) The maximum amount of time in seconds that the script can run before the
AWS IoT Greengrass Core software terminates the process.
This lifecycle step doesn't timeout by default. If you omit this timeout, the Run script
runs until it exits.
Setenv
(Optional) The dictionary of environment variables to provide to the script. These
environment variables override the variables that you provide in Lifecycle.Setenv.
Startup
(Optional) An object that defines the background process to run when the component
starts.
Use Startup to run a command that must exit successfully before dependent components
can start. For example, you might define a Startup step that starts the MySQL process
with /etc/init.d/mysqld start.
The component enters the STARTING state when this lifecycle step runs. If the Startup
script exits with a success code, the component enters the RUNNING state. Then, dependent
components can start.
Note
You can define only one Startup or Run lifecycle.
This object contains the following information:
Script
The script to run.
RequiresPrivilege
(Optional) You can run the script with root privileges. If you set this option to true,
then the AWS IoT Greengrass Core software runs this lifecycle script as root instead of
as the system user that you configure to run this component. Defaults to false.
478
AWS IoT Greengrass Developer Guide, Version 2
Recipe format
Skipif
(Optional) The check to determine whether or not to run the script. You can define to
check if an executable is on the path or if a file exists. If the output is true, then the
AWS IoT Greengrass Core software skips the step. Choose from the following checks:
• onpath runnable – Check if a runnable is on the system path. For example, use
onpath python3 to skip this lifecycle step if Python 3 is available.
• exists file – Check if a file exists. For example, use exists /tmp/my-
configuration.db to skip this lifecycle step if /tmp/my-configuration.db is
present.
Timeout
(Optional) The maximum amount of time in seconds that the script can run before the
AWS IoT Greengrass Core software terminates the process.
Default: 120 seconds
Setenv
(Optional) The dictionary of environment variables to provide to the script. These
environment variables override the variables that you provide in Lifecycle.Setenv.
Shutdown
(Optional) An object that defines the script to run when the component shuts down.
If you start a background process in Startup, use the Shutdown step to stop that process
when the component shuts down. For example, you might define a Shutdown step that
stops the MySQL process with /etc/init.d/mysqld stop.
The component enters the STOPPING state when this lifecycle step runs.
This object contains the following information:
Script
The script to run.
RequiresPrivilege
(Optional) You can run the script with root privileges. If you set this option to true,
then the AWS IoT Greengrass Core software runs this lifecycle script as root instead of
as the system user that you configure to run this component. Defaults to false.
Skipif
(Optional) The check to determine whether or not to run the script. You can define to
check if an executable is on the path or if a file exists. If the output is true, then the
AWS IoT Greengrass Core software skips the step. Choose from the following checks:
• onpath runnable – Check if a runnable is on the system path. For example, use
onpath python3 to skip this lifecycle step if Python 3 is available.
• exists file – Check if a file exists. For example, use exists /tmp/my-
configuration.db to skip this lifecycle step if /tmp/my-configuration.db is
present.
Timeout
(Optional) The maximum amount of time in seconds that the script can run before the
AWS IoT Greengrass Core software terminates the process.
Default: 15 seconds.
479
AWS IoT Greengrass Developer Guide, Version 2
Recipe format
Setenv
(Optional) The dictionary of environment variables to provide to the script. These
environment variables override the variables that you provide in Lifecycle.Setenv.
Recover
(Optional) An object that defines the script to run when the component encounters an error.
This step runs when a component enters the ERRORED state. If the component becomes
ERRORED three times without successfully recovering, the component changes to the
BROKEN state. To fix a BROKEN component, you must deploy it again.
This object contains the following information:
Script
The script to run.
RequiresPrivilege
(Optional) You can run the script with root privileges. If you set this option to true,
then the AWS IoT Greengrass Core software runs this lifecycle script as root instead of
as the system user that you configure to run this component. Defaults to false.
Skipif
(Optional) The check to determine whether or not to run the script. You can define to
check if an executable is on the path or if a file exists. If the output is true, then the
AWS IoT Greengrass Core software skips the step. Choose from the following checks:
• onpath runnable – Check if a runnable is on the system path. For example, use
onpath python3 to skip this lifecycle step if Python 3 is available.
• exists file – Check if a file exists. For example, use exists /tmp/my-
configuration.db to skip this lifecycle step if /tmp/my-configuration.db is
present.
Timeout
(Optional) The maximum amount of time in seconds that the script can run before the
AWS IoT Greengrass Core software terminates the process.
Default: 60 seconds.
Setenv
(Optional) The dictionary of environment variables to provide to the script. These
environment variables override the variables that you provide in Lifecycle.Setenv.
Selections
(Optional) A list of selection keys that specify sections of the global lifecycle (p. 482) to run
for this manifest. In the global lifecycle, you can define lifecycle steps with selection keys
at any level to select sub-sections of the lifecycle. Then, the core device uses those sections
that match the selection keys in this manifest. For more information, see the global lifecycle
examples (p. 482).
Important
The core device uses the selections from the global lifecycle only if this manifest
doesn't define a lifecycle.
You can specify the all selection key to run sections of the global lifecycle that don't have
selection keys.
480
AWS IoT Greengrass Developer Guide, Version 2
Recipe format
Artifacts
(Optional) A list of objects that each define a binary artifact for the component on the platform
that this manifest defines. For example, you can define code or images as artifacts.
When the component deploys, the AWS IoT Greengrass Core software downloads the artifact
to a folder on the core device. You can also define artifacts as archive files that the software
extracts after it downloads them.
You can use recipe variables (p. 484) to get the paths to the folders where the artifacts install
on the core device.
• Normal files – Use the artifacts:path recipe variable (p. 484) to get the path to the folder
that contains the artifacts. For example, specify {artifacts:path}/my_script.py in a
recipe to get the path to an artifact that has the URI s3://DOC-EXAMPLE-BUCKET/path/
to/my_script.py.
• Extracted archives – Use the artifacts:decompressedPath recipe variable (p. 485) to get the
path to the folder that contains the extracted archive artifacts. The AWS IoT Greengrass Core
software extracts each archive to a folder with the same name as the archive. For example,
specify {artifacts:decompressedPath}/my_archive/my_script.py in a recipe to
get the path to my_script.py in the archive artifact that has the URI s3://DOC-EXAMPLE-
BUCKET/path/to/my_archive.zip.
Note
When you develop a component with an archive artifact on a local core device, you
might not have a URI for that artifact. To test your component with an Unarchive
option that extracts the artifact, specify a URI where the file name matches the name
of your archive artifact file. You can specify the URI where you expect to upload the
archive artifact, or you can specify a new placeholder URI. For example, to extract the
my_archive.zip artifact during a local deployment, you can specify s3://DOC-
EXAMPLE-BUCKET/my_archive.zip.
Each object contains the following information:
URI
The URI of an artifact in an S3 bucket. The AWS IoT Greengrass Core software fetches the
artifact from this URI when the component installs, unless the artifact already exists on the
device. Each artifact must have a unique file name within each manifest.
Unarchive
(Optional) The type of archive to unpack. Choose from the following options:
• NONE – The file isn't an archive to unpack. The AWS IoT Greengrass Core software
installs the artifact to a folder on the core device. You can use the artifacts:path recipe
variable (p. 484) to get the path to this folder.
• ZIP – The file is a ZIP archive. The AWS IoT Greengrass Core software extracts
the archive to a folder with the same name as the archive. You can use the
artifacts:decompressedPath recipe variable (p. 485) to get the path to the folder that
contains this folder.
Defaults to NONE.
Permission
(Optional) An object that defines the access permissions to set for this artifact file. You can
set the read permission and the execute permission.
Note
You can't set the write permission, because the AWS IoT Greengrass Core software
doesn't allow components to edit artifact files in the artifacts folder. To edit an
481
AWS IoT Greengrass Developer Guide, Version 2
Recipe format
artifact file in a component, copy it to another location or publish and deploy a
new artifact file.
If you define an artifact as an archive to unpack, then the AWS IoT Greengrass Core
software sets these access permissions on the files that it unpacks from the archive. The
AWS IoT Greengrass Core software sets the folder's access permissions to ALL for Read
and Execute. This allows components to view the unpacked files in the folder. To set
permissions on individual files from the archive, you can set the permissions in the install
lifecycle script (p. 477).
This object contains the following information:
Read
(Optional) The read permission to set for this artifact file. To allow other components to
access this artifact, such as components that depend on this component, specify ALL.
Choose from the following options:
• NONE – The file isn't readable.
• OWNER – The file is readable by the system user that you configure to run this
component.
• ALL – The file is readable by all users.
Defaults to OWNER.
Execute
(Optional) The run permission to set for this artifact file. The Execute permission
implies the Read permission. For example, if you specify ALL for Execute, then all
users can read and run this artifact file.
Choose from the following options:
• NONE – The file isn't runnable.
• OWNER – The file is runnable by the system user that you configure to run the
component.
• ALL – The file is runnable by all users.
Defaults to NONE.
Digest
(Read-only) The cryptographic digest hash of the artifact. When you create a component,
AWS IoT Greengrass uses a hash algorithm to calculate a hash of the artifact file. Then,
when you deploy the component, the Greengrass nucleus calculates the hash of the
downloaded artifact and compares the hash with this digest to verify the artifact before
installation. If the hash doesn't match the digest, the deployment fails.
If you set this parameter, AWS IoT Greengrass replaces the value that you set when you
create the component.
Algorithm
(Read-only) The hash algorithm that AWS IoT Greengrass uses to calculate the digest hash
of the artifact.
If you set this parameter, AWS IoT Greengrass replaces the value that you set when you
create the component.
Lifecycle
An object that defines how to install and run the component. The core device uses the global
lifecycle only if the manifest (p. 474) to use doesn't specify a lifecycle.
482
AWS IoT Greengrass Developer Guide, Version 2
Recipe format
Note
You define this lifecycle outside a manifest. You can also define a manifest
lifecycle (p. 476) that applies to the platforms that match that manifest.
In the global lifecycle, you can specify lifecycles that run for certain selection keys (p. 480) that you
specify in each manifest. Selection keys are strings that identify sections of the global lifecycle to
run for each manifest.
The all selection key is the default on any section without a selection key. This means that you
can specify the all selection key in a manifest to run the sections of the global lifecycle without
selection keys. You don't need to specify the all selection key in the global lifecycle.
If a manifest doesn't define a lifecycle or selection keys, the core device defaults to use the all
selection. This means that in this case, the core device uses the sections of the global lifecycle that
don't use selection keys.
This object contains the same information as the manifest lifecycle (p. 476), but you can specify
selection keys at any level to select sub-sections of the lifecycle.
Tip
We recommend that you use only lowercase letters for each selection key to avoid conflicts
between selection keys and lifecycle keys. Lifecycle keys start with a capital letter.
Example Example global lifecycle with top-level selection keys
Lifecycle:
key1:
Install:
Skipif: onpath executable | exists file
Script: command1
key2:
Install:
Script: command2
all:
Install:
Script: command3
Example Example global lifecycle with bottom-level selection keys
Lifecycle:
Install:
Script:
key1: command1
key2: command2
all: command3
Example Example global lifecycle with multiple levels of selection keys
Lifecycle:
key1:
Install:
Skipif: onpath executable | exists file
Script: command1
key2:
Install:
Script: command2
all:
Install:
Script:
key3: command3
key4: command4
483
AWS IoT Greengrass Developer Guide, Version 2
Recipe variables
all: command5
Recipe variables
Recipe variables expose information from the current component and nucleus for you to use in your
recipes. You can use recipe variables within lifecycle definitions in component recipes. For example, use a
recipe variable to pass component configuration parameters to an application that you run in a lifecycle
script.
Recipe variables use {recipe_variable} syntax. The curly braces indicate a recipe variable.
AWS IoT Greengrass supports the following recipe variables:
component_dependency_name:configuration:json_pointer
The value of a configuration parameter for the component that this recipe defines or for a
component on which this component depends.
You can use this variable to provide a parameter to a script that you run in the component lifecycle.
This recipe variable has the following inputs:
• component_dependency_name – (Optional) The name of the component dependency to query.
Omit this segment to query the component that this recipe defines. You can specify only direct
dependencies.
• json_pointer – The JSON pointer to the configuration value to evaluate. JSON pointers start
with a forward slash /. To identify a value in a nested component configuration, use forward
slashes (/) to separate the keys for each level in the configuration. You can use a number as a key
to specify an index in a list. For more information, see the JSON pointer specification.
AWS IoT Greengrass Core uses JSON pointers for recipes in YAML format.
The JSON pointer can reference the following node types:
• A value node. AWS IoT Greengrass Core replaces the recipe variable with the string representation
of the value. Null values convert to null as a string.
• An object node. AWS IoT Greengrass Core replaces the recipe variable with the serialized JSON
string representation of that object.
• No node. AWS IoT Greengrass Core doesn't replace the recipe variable.
For example, the {configuration:/Message} recipe variable retrieves
the value of the Message key in the component configuration. The
{com.example.MyComponentDependency:configuration:/server/port} recipe variable
retrieves the value of port in the server configuration object of a component dependency.
component_dependency_name:artifacts:path
The root path of the artifacts for the component that this recipe defines or for a component on
which this component depends.
When a component installs, AWS IoT Greengrass copies the component's artifacts to the folder
that this variable exposes. You can use this variable to identify the location of a script to run in the
component lifecycle, for example.
The folder at this path is read-only. To modify artifact files, copy the files to another location, such
as the current working directory ($PWD or .). Then, modify the files there.
To read or run an artifact from a component dependency, that artifact's Read or Execute
permission must be ALL. For more information, see the artifact permissions (p. 481) that you
define in the component recipe.
484
AWS IoT Greengrass Developer Guide, Version 2
Recipe examples
This recipe variable has the following inputs:
• component_dependency_name – (Optional) The name of the component dependency to query.
Omit this segment to query the component that this recipe defines. You can specify only direct
dependencies.
component_dependency_name:artifacts:decompressedPath
The root path of the decompressed archive artifacts for the component that this recipe defines or for
a component on which this component depends.
When a component installs, AWS IoT Greengrass unpacks the component's archive artifacts to the
folder that this variable exposes. You can use this variable to identify the location of a script to run
in the component lifecycle, for example.
Each artifact unzips to a folder within the decompressed path, where the folder has the same name
as the artifact minus its extension. For example, a ZIP artifact named models.zip unpacks to the
{artifacts:decompressedPath}/models folder.
The folder at this path is read-only. To modify artifact files, copy the files to another location, such
as the current working directory ($PWD or .). Then, modify the files there.
To read or run an artifact from a component dependency, that artifact's Read or Execute
permission must be ALL. For more information, see the artifact permissions (p. 481) that you
define in the component recipe.
This recipe variable has the following inputs:
• component_dependency_name – (Optional) The name of the component dependency to query.
Omit this segment to query the component that this recipe defines. You can specify only direct
dependencies.
component_dependency_name:work:path
This feature is available for v2.0.4 and later of the Greengrass nucleus component (p. 181).
The work path for the component that this recipe defines or for a component on which this
component depends. The value of this recipe variable is equivalent to the output of the $PWD
environment variable and the pwd command when run from the context of the component.
You can use this recipe variable to share files between a component and a dependency.
The folder at this path is readable and writable by the component that this recipe defines and by
other components that run as the same user and group.
This recipe variable has the following inputs:
• component_dependency_name – (Optional) The name of the component dependency to query.
Omit this segment to query the component that this recipe defines. You can specify only direct
dependencies.
kernel:rootPath
The AWS IoT Greengrass Core root path.
iot:thingName
This feature is available for v2.3.0 and later of the Greengrass nucleus component (p. 181).
The name of the core device's AWS IoT thing.
Recipe examples
You can reference the following recipe examples to help you create recipes for your components.
485
AWS IoT Greengrass Developer Guide, Version 2
Recipe examples
Topics
• Hello World component recipe (p. 486)
• Python runtime component example (p. 487)
• Component recipe that specifies several fields (p. 487)
Hello World component recipe
The following recipe describes a Hello World component that runs a Python script. This component
supports all platforms and accepts a Message parameter that AWS IoT Greengrass passes as an
argument to the Python script. This is the recipe for the Hello World component in the Getting started
tutorial (p. 31).
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.HelloWorld",
"ComponentVersion": "1.0.0",
"ComponentDescription": "My first AWS IoT Greengrass component.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"Message": "world"
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"Run": "python3 -u {artifacts:path}/hello_world.py \"{configuration:/
Message}\""
}
},
{
"Platform": {
"os": "windows"
},
"Lifecycle": {
"Run": "py -3 -u {artifacts:path}/hello_world.py \"{configuration:/Message}\""
}
}
]
}
YAML
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.HelloWorld
ComponentVersion: '1.0.0'
ComponentDescription: My first AWS IoT Greengrass component.
ComponentPublisher: Amazon
ComponentConfiguration:
DefaultConfiguration:
Message: world
Manifests:
- Platform:
os: linux
486
AWS IoT Greengrass Developer Guide, Version 2
Recipe examples
Lifecycle:
Run: |
python3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
- Platform:
os: windows
Lifecycle:
Run: |
py -3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
Python runtime component example
The following recipe describes a component that installs Python. This component supports 64-bit Linux
devices.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.PythonRuntime",
"ComponentDescription": "Installs Python 3.7",
"ComponentPublisher": "Amazon",
"ComponentVersion": "1.1.0",
"Manifests": [
{
"Platform": {
"os": "linux",
"architecture": "amd64"
},
"Lifecycle": {
"Install": "apt-get install python3.7"
}
}
]
}
YAML
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.PythonRuntime
ComponentDescription: Installs Python 3.7
ComponentPublisher: Amazon
ComponentVersion: '1.1.0'
Manifests:
- Platform:
os: linux
architecture: amd64
Lifecycle:
Install:
apt-get install python3.7
Component recipe that specifies several fields
The following component recipe uses several recipe fields.
JSON
487
AWS IoT Greengrass Developer Guide, Version 2
Recipe examples
"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"
}
},
"Artifacts": [
{
"URI": "s3://DOC-EXAMPLE-BUCKET/hello_world.zip",
"Unarchive": "ZIP"
},
{
"URI": "s3//DOC-EXAMPLE-BUCKET/hello-world2.py"
}
]
},
{
"Lifecycle": {
"Start": {
"Skipif": "onpath git",
"Script": "sudo apt-get install git"
}
},
"Artifacts": [
{
"URI": "s3://DOC-EXAMPLE-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'
488
AWS IoT Greengrass Developer Guide, Version 2
Environment variables
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
Artifacts:
- URI: s3://DOC-EXAMPLE-BUCKET/hello_world.zip
Unarchive: ZIP
- URI: s3//DOC-EXAMPLE-BUCKET/hello-world2.py
- Lifecycle:
Install:
Skipif: onpath git
Script: sudo apt-get install git
Artifacts:
- URI: s3://DOC-EXAMPLE-BUCKET/hello_world.py
Component environment variable reference
The AWS IoT Greengrass Core software sets environment variables when it runs lifecycle scripts for
components. You can get these environment variables in your components to get the thing name,
AWS Region, and Greengrass nucleus version. The software also sets environment variables that your
component requires to use the interprocess communication SDK (p. 545) and to interact with AWS
services (p. 454).
You can also set custom environment variables for your component's lifecycle scripts. For more
information, see Setenv (p. 476).
The AWS IoT Greengrass Core software sets the following environment variables:
AWS_IOT_THING_NAME
The name of the AWS IoT thing that represents this Greengrass core device.
AWS_REGION
The AWS Region where this Greengrass core device operates.
The AWS SDKs use this environment variable to identify the default Region to use. This variable is
equivalent to AWS_DEFAULT_REGION.
AWS_DEFAULT_REGION
The AWS Region where this Greengrass core device operates.
The AWS CLI uses this environment variable to identify the default Region to use. This variable is
equivalent to AWS_REGION.
GGC_VERSION
The version of the Greengrass nucleus component (p. 181) that runs on this Greengrass core device.
489
AWS IoT Greengrass Developer Guide, Version 2
Environment variables
AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT
The path to the IPC socket that components use to communicate with the AWS IoT Greengrass
Core software. For more information, see Use the AWS IoT Device SDK to communicate with the
Greengrass nucleus, other components, and AWS IoT Core (p. 545).
SVCUID
The secret token that components use to connect to the IPC socket and communicate with the
AWS IoT Greengrass Core software. For more information, see Use the AWS IoT Device SDK to
communicate with the Greengrass nucleus, other components, and AWS IoT Core (p. 545).
AWS_CONTAINER_AUTHORIZATION_TOKEN
The secret token that components use to retrieve credentials from the token exchange service
component (p. 407).
AWS_CONTAINER_CREDENTIALS_FULL_URI
The URI that components request to retrieve credentials from the token exchange service
component (p. 407).
490
AWS IoT Greengrass Developer Guide, Version 2
Deploy AWS IoT Greengrass
components to devices
You can deploy components to individual devices or groups of devices with AWS IoT Greengrass. With
deployments, you define the AWS IoT Greengrass components and configurations to deploy to core
devices. AWS IoT Greengrass deploys to target devices, which are AWS IoT things or thing groups that
represent Greengrass core devices. AWS IoT Greengrass uses AWS IoT Core jobs to deploy to your core
devices, so you can configure how the job rolls out to your devices.
Each core device runs the combination of the software from the deployments that target the device.
However, deployments to the same target overwrite previous deployments to that target. When you
create a deployment, you define the components and configurations to apply to the core devices'
existing software. When you revise a deployment for a target, you replace the components from the
previous revision with the components in the new revision. For example, you deploy components A and
B to a thing group X. You then deploy components B and C to a different thing group Y. As a result, the
components A, B, and C all run on any core device that is a member of both groups. Then, you create
another deployment to thing group X that specifies only component B. As a result, the core devices in
that group no longer run component A.
Note
When you remove a core device from a thing group, the component deployment behavior
depends on the version of the Greengrass nucleus (p. 181) that the core device runs.
2.5.1 and later
The thing group removal behavior depends on whether the core device's AWS IoT policy
grants the greengrass:ListThingGroupsForCoreDevice permission. For more
information about this permission and AWS IoT policies for core devices, see Device
authentication and authorization for AWS IoT Greengrass (p. 773).
• If the AWS IoT policy grants this permission
When you remove a core device from a thing group, AWS IoT Greengrass removes that
thing group's components from the device in the next deployment. However, if another
deployment targets the core device and includes a component, the core device doesn't
remove that component.
• If the AWS IoT policy doesn't grant this permission
When you remove a core device from a thing group, AWS IoT Greengrass doesn't delete
that thing group's components from the device. Because of this, we recommend that you
don't remove core devices from thing groups where you deploy components.
To remove a component from a device, where the device is no longer a member of the
thing group that deploys that component, use the deployment create (p. 434) command
of the Greengrass CLI. Specify the component to remove with the --remove argument,
and specify the thing group with the --groupId argument.
2.5.0
When you remove a core device from a thing group, AWS IoT Greengrass removes that
thing group's components from the device in the next deployment. However, if another
491
AWS IoT Greengrass Developer Guide, Version 2
deployment targets the core device and includes a component, the core device doesn't
remove that component.
This behavior requires that the core device's AWS IoT policy grants the
greengrass:ListThingGroupsForCoreDevice permission. If a core device doesn't
have this permission, the core device fails to apply deployments. For more information, see
Device authentication and authorization for AWS IoT Greengrass (p. 773).
2.0.x - 2.4.x
When you remove a core device from a thing group, AWS IoT Greengrass doesn't delete that
thing group's components from the device. Because of this, we recommend that you don't
remove core devices from thing groups where you deploy components.
To remove a component from a device, where the device is no longer a member of the
thing group that deploys that component, use the deployment create (p. 434) command of
the Greengrass CLI. Specify the component to remove with the --remove argument, and
specify the thing group with the --groupId argument.
Deployments are continuous. When you create a deployment, AWS IoT Greengrass rolls out the
deployment to target devices that are online. If a target device isn't online, then it receives the
deployment the next time it connects to AWS IoT Greengrass. When you add a core device to a target
thing group, AWS IoT Greengrass sends the device the latest deployment for that thing group.
Each target thing or thing group can have one deployment at a time. This means that when you create
a deployment for a target, AWS IoT Greengrass no longer deploys the previous revision of that target's
deployment.
Deployments provide several options that let you control which devices receive an update and how the
update deploys. When you create a deployment, you can configure the following options:
• AWS IoT Greengrass components
Define the components to install and run on the target devices. AWS IoT Greengrass components are
software modules that you deploy and run on Greengrass core devices. Devices receive components
only if the component supports the device's platform. This lets you deploy to groups of devices even
if the target devices run on multiple platforms. If a component doesn't support the device's platform,
the component doesn't deploy to the device.
You can deploy custom components and AWS-provided components to your devices. When you deploy
a component, AWS IoT Greengrass identifies any component dependencies and deploys them too.
For more information, see Develop AWS IoT Greengrass components (p. 440) and AWS-provided
components (p. 175).
You define the version and configuration update to deploy for each component. The configuration
update specifies how to modify the component's existing configuration on the core device, or the
component's default configuration if the component doesn't exist on the core device. You can specify
which configuration values to reset to default values and the new configuration values to merge onto
the core device. For more information, see Update component configurations (p. 500).
Important
When you deploy a component, AWS IoT Greengrass installs the latest supported versions of
all component dependencies for that component. Because of this, new patch versions of AWS-
provided public components might be automatically deployed to your core devices if you add
new devices to a thing group, or you update the deployment that targets those devices. Some
automatic updates, such as a nucleus update, can cause your devices to restart unexpectedly.
To prevent unintended updates for a component that is running on your device, we
recommend that you directly include your preferred version of that component when you
create a deployment (p. 493). For more information about update behavior for AWS IoT
Greengrass Core software, see Update the AWS IoT Greengrass Core software (OTA) (p. 170).
492
AWS IoT Greengrass Developer Guide, Version 2
Create deployments
• Deployment policies
Define when it's safe to deploy a configuration and what to do if the deployment fails. You can specify
whether or not to wait for components to report that they can update. You can also specify whether or
not to roll back devices to their previous configuration if they apply a deployment that fails.
• Stop configuration
Define when and how to stop a deployment. The deployment stops and fails if the criteria that you
define are met. For example, you can configure a deployment to stop if a percentage of devices fail to
apply that deployment after a minimum number of devices receive it.
• Rollout configuration
Define the rate at which a deployments rolls out to the target devices. You can configure an
exponential rate increase with minimum and maximum rate bounds.
• Timeout configuration
Define the maximum amount of time each device has to apply a deployment. If a device exceeds the
duration that you specify, then the device fails to apply the deployment.
Important
Custom components can define artifacts in S3 buckets. When the AWS IoT Greengrass Core
software deploys a component, it downloads the component's artifacts from the AWS Cloud.
Core device roles don't allow access to S3 buckets by default. To deploy custom components
that define artifacts in an S3 bucket, the core device role must grant permissions to download
artifacts from that bucket. For more information, see Allow access to S3 buckets for component
artifacts (p. 792).
Topics
• Create deployments (p. 493)
• Revise deployments (p. 502)
• Cancel deployments (p. 504)
• Check deployment status (p. 504)
Create deployments
You can create a deployment that targets a thing or thing group.
When you create a deployment, you configure the software components to deploy and how the
deployment job rolls out to target devices. You can define the deployment in the JSON file that you
provide to the AWS CLI.
The deployment target determines the devices on which you want to run your components. To deploy to
one core device, specify a thing. To deploy to multiple core devices, specify a thing group that includes
those devices. For more information about how to configure thing groups, see Static thing groups and
Dynamic thing groups in the AWS IoT Developer Guide.
Follow the steps in this section to create a deployment to a target. For more information about how to
update the software components on a target that has a deployment, see Revise deployments (p. 502).
Warning
The CreateDeployment operation can uninstall components from core devices. If a component
is present in the previous deployment and not the new deployment, the core device uninstalls
that component. To avoid uninstalling components, first use the ListDeployments operation
to check if the target for the deployment already has an existing deployment. Then, use the
493
AWS IoT Greengrass Developer Guide, Version 2
Create deployments
GetDeployment operation to start from that existing deployment when you create a new
deployment.
To create a deployment (AWS CLI)
1. Create a file called deployment.json, and then copy the following JSON object into the file.
Replace targetArn with the ARN of the AWS IoT thing or thing group to target for the deployment.
Thing and thing group ARNs have the following format:
• Thing: arn:aws:iot:region:account-id:thing/thingName
• Thing group: arn:aws:iot:region:account-id:thinggroup/thingGroupName
{
"targetArn": "targetArn"
}
2. Check if the deployment target has an existing deployment that you want to revise. Do the
following:
a. Run the following command to list the deployments for the deployment target. Replace
targetArn with the ARN of the target AWS IoT thing or thing group.
aws greengrassv2 list-deployments --target-arn targetArn
The response contains a list with the latest deployment for the target. If the response is
empty, the target doesn't have an existing deployment, and you can skip to Step 3 (p. 494).
Otherwise, copy the deploymentId from the response to use in the next step.
Note
You can also revise a deployment other than the latest revision for the target. Specify
the --history-filter ALL argument to list all deployments for the target. Then,
copy the ID of the deployment that you want to revise.
b. Run the following command to get the deployment's details. These details include metadata,
components, and job configuration. Replace deploymentId with the ID from the previous step.
aws greengrassv2 get-deployment --deployment-id deploymentId
The response contains the deployment's details.
c. Copy any of the following key-value pairs from the previous command's response into
deployment.json. You can change these values for the new deployment.
• deploymentName – The deployment's name.
• components – The deployment's components. To uninstall a component, remove it from this
object.
• deploymentPolicies – The deployment's policies.
• iotJobConfiguration – The deployment's job configuration.
• tags – The deployment's tags.
3. (Optional) Define a name for the deployment. Replace deploymentName with the name of the
deployment.
{
"targetArn": "targetArn",
"deploymentName": "deploymentName"
}
494
AWS IoT Greengrass Developer Guide, Version 2
Create deployments
4. Add each component to deploy the target devices. To do so, add key-value pairs to the components
object, where the key is the component name, and the value is an object that contains the details for
that component. Specify the following details for each component that you add:
• version – The component version to deploy.
• configurationUpdate – The configuration update (p. 500) to deploy. The update is a patch
operation that modifies the component's existing configuration on each target device, or the
component's default configuration if it doesn't exist on the target device. You can specify the
following configuration updates:
• Reset updates (reset) – (Optional) A list of JSON pointers that define the configuration
values to reset to their default values on the target device. The AWS IoT Greengrass Core
software applies reset updates before it applies merge updates. For more information, see Reset
updates (p. 500).
• Merge updates (merge) – (Optional) A JSON document that defines the configuration values
to merge onto the target device. You must serialize the JSON document as a string. For more
information, see Merge updates (p. 500).
•
runWith – (Optional) The system process options that the AWS IoT Greengrass Core software
uses to run this component's processes on the core device. If you omit a parameter in the runWith
object, the AWS IoT Greengrass Core software uses the default values that you configure on the
Greengrass nucleus component (p. 181).
You can specify any of the following options:
• posixUser – The POSIX system user and, optionally, group to use to run this component on
Linux core devices. The user, and group if specified, must exist on each Linux core device. Specify
the user and group separated by a colon (:) in the following format: user:group. The group is
optional. If you don't specify a group, the AWS IoT Greengrass Core software uses the primary
group for the user. For more information, see Configure the user that runs components (p. 161).
• windowsUser – The Windows user to use to run this component on Windows core devices. The
user must exist on each Windows core device, and its name and password must be stored in the
LocalSystem account's Credentials Manager instance. For more information, see Configure the
user that runs components (p. 161).
This feature is available for v2.5.0 and later of the Greengrass nucleus component (p. 181).
• systemResourceLimits – The system resource limits to apply to this component's processes.
You can apply system resource limits to generic and non-containerized Lambda components.
For more information, see Configure system resource limits for components (p. 164).
You can specify any of the following options:
• cpus – The maximum amount of CPU time that this component's processes can use on
the core device. A core device's total CPU time is equivalent to the device's number of CPU
cores. For example, on a core device with 4 CPU cores, you can set this value to 2 to limit this
component's processes to 50 percent usage of each CPU core. On a device with 1 CPU core,
you can set this value to 0.25 to limit this component's processes to 25 percent usage of the
CPU. If you set this value to a number greater than the number of CPU cores, the AWS IoT
Greengrass Core software doesn't limit the component's CPU usage.
• memory – The maximum amount of RAM (in kilobytes) that this component's processes can
use on the core device.
This feature is available for v2.4.0 and later of the Greengrass nucleus component (p. 181). AWS
IoT Greengrass doesn't currently support this feature on Windows core devices.
495
AWS IoT Greengrass Developer Guide, Version 2
Create deployments
Example Example basic configuration update
The following example components object specifies to deploy a component,
com.example.PythonRuntime, that expects a configuration parameter named pythonVersion.
{
"targetArn": "targetArn",
"deploymentName": "deploymentName",
"components": {
"com.example.PythonRuntime": {
"componentVersion": "1.0.0",
"configurationUpdate": {
"merge": "{\"pythonVersion\":\"3.7\"}"
}
}
}
}
Example Example configuration update with reset and merge updates
Consider an example industrial dashboard component, com.example.IndustrialDashboard,
that has the following default configuration.
{
"name": null,
"mode": "REQUEST",
"network": {
"useHttps": true,
"port": {
"http": 80,
"https": 443
},
},
"tags": []
}
The following configuration update specifies the following instructions:
1. Reset the HTTPS setting to its default value (true).
2. Reset the list of industrial tags to an empty list.
3. Merge a list of industrial tags that identify temperature and pressure data streams for two boilers.
{
"reset": [
"/network/useHttps",
"/tags"
],
"merge": {
"tags": [
"/boiler/1/temperature",
"/boiler/1/pressure",
"/boiler/2/temperature",
"/boiler/2/pressure"
]
}
}
496
AWS IoT Greengrass Developer Guide, Version 2
Create deployments
The following example components object specifies to deploy this industrial dashboard component
and configuration update.
{
"targetArn": "targetArn",
"deploymentName": "deploymentName",
"components": {
"com.example.IndustrialDashboard": {
"componentVersion": "1.0.0",
"configurationUpdate": {
"reset": [
"/network/useHttps",
"/tags"
],
"merge": "{\"tags\":[\"/boiler/1/temperature\",\"/boiler/1/pressure\",\"/
boiler/2/temperature\",\"/boiler/2/pressure\"]}"
}
}
}
}
5. (Optional) Define deployment policies for the deployment. You can configure when core devices can
safely apply a deployment or what to do if a core device fails to apply the deployment. To do so, add
a deploymentPolicies object to deployment.json, and then do any of the following:
1. (Optional) Specify the component update policy (componentUpdatePolicy). This policy defines
whether or not the deployment lets components defer an update until they are ready to update.
For example, components may need to clean up resources or finish critical actions before they can
restart to apply an update. This policy also defines the amount of time that components have to
respond to an update notification.
This policy is an object with the following parameters:
• action – (Optional) Whether or not to notify components and wait for them to report when
they're ready to update. Choose from the following options:
• NOTIFY_COMPONENTS – The deployment notifies each component before it stops and
updates that component. Components can use the SubscribeToComponentUpdates (p. 603)
IPC operation to receive these notifications.
• SKIP_NOTIFY_COMPONENTS – The deployment doesn't notify components or wait for them
to be safe to update.
Defaults to NOTIFY_COMPONENTS.
• timeoutInSeconds The amount of time in seconds that each component has to respond to an
update notification with the DeferComponentUpdate (p. 604) IPC operation. If the component
doesn't respond within this amount of time, then the deployment proceeds on the core device.
Defaults to 60 seconds.
2. (Optional) Specify the configuration validation policy (configurationValidationPolicy).
This policy defines how long each component has to validate a configuration update from a
deployment. Components can use the SubscribeToValidateConfigurationUpdates (p. 609) IPC
operation to subscribe to notifications for their own configuration updates. Then, components
can use the SendConfigurationValidityReport (p. 610) IPC operation to tell the AWS IoT
Greengrass Core software if the configuration update is valid. If the configuration update isn't
valid, the deployment fails.
This policy is an object with the following parameter:
497
AWS IoT Greengrass Developer Guide, Version 2
Create deployments
• timeoutInSeconds (Optional) The amount of time in seconds that each component has to
validate a configuration update. If the component doesn't respond within this amount of time,
then the deployment proceeds on the core device.
Defaults to 30 seconds.
3. (Optional) Specify the failure handling policy (failureHandlingPolicy). This policy is a
string that defines whether or not to roll back devices if the deployment fails. Choose from the
following options:
• ROLLBACK – If the deployment fails on a core device, then the AWS IoT Greengrass Core
software rolls back that core device to its previous configuration.
• DO_NOTHING – If the deployment fails on a core device, then the AWS IoT Greengrass Core
software keeps the new configuration. This can result in broken components if the new
configuration isn't valid.
Defaults to ROLLBACK.
Your deployment in deployment.json may look similar to the following example:
{
"targetArn": "targetArn",
"deploymentName": "deploymentName",
"components": {
"com.example.IndustrialDashboard": {
"componentVersion": "1.0.0",
"configurationUpdate": {
"reset": [
"/network/useHttps",
"/tags"
],
"merge": "{\"tags\":[\"/boiler/1/temperature\",\"/boiler/1/pressure\",\"/
boiler/2/temperature\",\"/boiler/2/pressure\"]}"
}
}
},
"deploymentPolicies": {
"componentUpdatePolicy": {
"action": "NOTIFY_COMPONENTS",
"timeoutInSeconds": 30
},
"configurationValidationPolicy": {
"timeoutInSeconds": 60
},
"failureHandlingPolicy": "ROLLBACK"
}
}
6. (Optional) Define how the deployment stops, rolls out, or times out. AWS IoT Greengrass uses
AWS IoT Core jobs to send deployments to core devices, so these options are identical to the
configuration options for AWS IoT Core jobs. For more information, see Job rollout and abort
configuration in the AWS IoT Developer Guide.
To define the job options, add an iotJobConfigurations object to deployment.json. Then,
define the options to configure.
Your deployment in deployment.json may look similar to the following example:
{
"targetArn": "targetArn",
"deploymentName": "deploymentName",
498
AWS IoT Greengrass Developer Guide, Version 2
Create deployments
"components": {
"com.example.IndustrialDashboard": {
"componentVersion": "1.0.0",
"configurationUpdate": {
"reset": [
"/network/useHttps",
"/tags"
],
"merge": "{\"tags\":[\"/boiler/1/temperature\",\"/boiler/1/pressure\",\"/
boiler/2/temperature\",\"/boiler/2/pressure\"]}"
}
}
},
"deploymentPolicies": {
"componentUpdatePolicy": {
"action": "NOTIFY_COMPONENTS",
"timeoutInSeconds": 30
},
"configurationValidationPolicy": {
"timeoutInSeconds": 60
},
"failureHandlingPolicy": "ROLLBACK"
},
"iotJobConfigurations": {
"abortConfig": {
"criteriaList": [
{
"action": "CANCEL",
"failureType": "ALL",
"minNumberOfExecutedThings": 100,
"thresholdPercentage": 5
}
]
},
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": 5,
"incrementFactor": 2,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": 10,
"numberOfSucceededThings": 5
}
},
"maximumPerMinute": 50
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": 5
}
}
}
7. (Optional) Add tags (tags) for the deployment. For more information, see Tag your AWS IoT
Greengrass Version 2 resources (p. 919).
8. Run the following command to create the deployment from deployment.json.
aws greengrassv2 create-deployment --cli-input-json file://deployment.json
The response includes a deploymentId that identifies this deployment. You can use the
deployment ID to check the status of the deployment. For more information, see Check deployment
status (p. 505).
499
AWS IoT Greengrass Developer Guide, Version 2
Update component configurations
Update component configurations
Component configurations are JSON objects that define the parameters for each component. Each
component's recipe defines its default configuration, which you modify when you deploy components to
core devices.
When you create a deployment, you can specify the configuration update to apply for each component.
Configuration updates are patch operations, which means that the update modifies the component
configuration that exists on the core device. If the core device doesn't have the component, then the
configuration update modifies and applies the default configuration for that deployment.
The configuration update defines reset updates and merge updates. Reset updates define which
configuration values to reset to their defaults or remove. Merge updates define the new configuration
values to set for the component. When you deploy a configuration update, the AWS IoT Greengrass Core
software runs the reset update before the merge update.
Components can validate the configuration updates that you deploy. The component subscribes to
receive a notification when a deployment changes its configuration, and it can reject a configuration that
it doesn't support. For more information, see Interact with component configuration (p. 606).
Topics
• Reset updates (p. 500)
• Merge updates (p. 500)
• Examples (p. 501)
Reset updates
Reset updates define which configuration values to reset to their default values on the core device. If
a configuration value doesn't have a default value, then the reset update removes that value from the
component's configuration. This can help you fix a component that breaks as the result of an invalid
configuration.
Use a list of JSON pointers to define which configuration values to reset. JSON pointers start with
a forward slash /. To identify a value in a nested component configuration, use forward slashes (/)
to separate the keys for each level in the configuration. For more information, see the JSON pointer
specification.
Note
You can reset only an entire list to its default values. You can't use reset updates to reset an
individual element in a list.
To reset a component's entire configuration to its default values, specify a single empty string as the
reset update.
"reset": [""]
Merge updates
Merge updates define the configuration values to insert into the component configuration on the core.
The merge update is a JSON object that the AWS IoT Greengrass Core software merges after it resets the
values in the paths that you specify in the reset update. When you use the AWS CLI or AWS SDKs, you
must serialize this JSON object as a string.
You can merge a key-value pair that doesn't exist in the component's default configuration. You can
also merge a key-value pair that has a different type than the value with the same key. The new value
replaces the old value. This means that you can change the configuration object's structure.
500
AWS IoT Greengrass Developer Guide, Version 2
Update component configurations
You can merge null values and empty strings, lists, and objects.
Note
You can't use merge updates for the purpose of inserting or appending an element to a list. You
can replace an entire list, or you can define an object where each element has a unique key.
AWS IoT Greengrass uses JSON for configuration values. JSON specifies a number type but
doesn't differentiate between integers and floats. As a result, configuration values might convert
to floats in AWS IoT Greengrass. To ensure that your component uses the correct data type, we
recommend that you define numeric configuration values as strings. Then, have your component
parse them as integers or floats. This ensures that your configuration values have the same type
in the configuration and on your core device.
Examples
The following example demonstrates configuration updates for a dashboard component that has
the following default configuration. This example component displays information about industrial
equipment.
{
"name": null,
"mode": "REQUEST",
"network": {
"useHttps": true,
"port": {
"http": 80,
"https": 443
},
},
"tags": []
}
Then, you apply the following configuration update, which specifies a merge update but not a reset
update. This configuration tells the component to display the dashboard on HTTP port 8080 with data
from two boilers.
{
"merge": {
"name": "Factory 2A",
"network": {
"useHttps": false,
"port": {
"http": 8080
}
},
"tags": [
"/boiler/1/temperature",
"/boiler/1/pressure",
"/boiler/2/temperature",
"/boiler/2/pressure"
]
}
}
After this update, the dashboard component has the following configuration.
{
"name": "Factory 2A",
"mode": "REQUEST",
"network": {
501
AWS IoT Greengrass Developer Guide, Version 2
Revise deployments
"useHttps": false,
"port": {
"http": 8080,
"https": 443
}
},
"tags": [
"/boiler/1/temperature",
"/boiler/1/pressure",
"/boiler/2/temperature",
"/boiler/2/pressure"
]
}
Then, apply the following configuration update to display the dashboard on the default HTTPS port with
data from different boilers.
{
"reset": [
"/network/useHttps",
"/tags"
],
"merge": {
"tags": [
"/boiler/3/temperature",
"/boiler/3/pressure",
"/boiler/4/temperature",
"/boiler/4/pressure"
]
}
}
After this update, the dashboard component has the following configuration.
{
"name": "Factory 2A",
"mode": "REQUEST",
"network": {
"useHttps": true,
"port": {
"http": 8080,
"https": 443
}
},
"tags": [
"/boiler/3/temperature",
"/boiler/3/pressure",
"/boiler/4/temperature",
"/boiler/4/pressure",
]
}
Revise deployments
Each target thing or thing group can have one active deployment at a time. When you create a
deployment for a target that already has a deployment, the software components in the new
deployment replace those from the previous deployment. If the new deployment doesn't define a
component that the previous deployment defines, the AWS IoT Greengrass Core software removes that
502
AWS IoT Greengrass Developer Guide, Version 2
Revise deployments
component from the target core devices. You can revise an existing deployment so that you don't remove
the components that run on core devices from a previous deployment to a target.
To revise a deployment, you create a deployment that starts from the same components and
configurations that exist in a previous deployment. You use the CreateDeployment operation, which is
the same operation that you use to create deployments (p. 493).
To revise a deployment (AWS CLI)
1. Run the following command to list the deployments for the deployment target. Replace targetArn
with the ARN of the target AWS IoT thing or thing group.
aws greengrassv2 list-deployments --target-arn targetArn
The response contains a list with the latest deployment for the target. Copy the deploymentId
from the response to use in the next step.
Note
You can also revise a deployment other than the latest revision for the target. Specify the
--history-filter ALL argument to list all deployments for the target. Then, copy the
ID of the deployment that you want to revise.
2. Run the following command to get the deployment's details. These details include metadata,
components, and job configuration. Replace deploymentId with the ID from the previous step.
aws greengrassv2 get-deployment --deployment-id deploymentId
The response contains the deployment's details.
3. Create a file called deployment.json and copy the previous command's response into the file.
4. Remove the following key-value pairs from the JSON object in deployment.json:
• deploymentId
• revisionId
• iotJobId
• iotJobArn
• creationTimestamp
• isLatestForTarget
• deploymentStatus
The CreateDeployment operation expects a payload with the following structure.
{
"targetArn": "String",
"components": Map of components,
"deploymentPolicies": DeploymentPolicies,
"iotJobConfiguration": DeploymentIoTJobConfiguration,
"tags": Map of tags
}
5. In deployment.json, do any of the following:
• Change the deployment's name (deploymentName).
• Change the deployment's components (components).
• Change the deployment's policies (deploymentPolicies).
• Change the deployment's job configuration (iotJobConfiguration).
• Change the deployment's tags (tags).
503
AWS IoT Greengrass Developer Guide, Version 2
Cancel deployments
For more information about how to define these deployment details, see Create
deployments (p. 493).
6. Run the following command to create the deployment from deployment.json.
aws greengrassv2 create-deployment --cli-input-json file://deployment.json
The response includes a deploymentId that identifies this deployment. You can use the
deployment ID to check the status of the deployment. For more information, see Check deployment
status (p. 505).
Cancel deployments
You can cancel an active deployment to prevent its software components from installing on AWS IoT
Greengrass core devices. If you cancel a deployment that targets a thing group, core devices that you add
to the group won't receive that continuous deployment. If a core device already runs the deployment,
you won't change the components on that device when you cancel the deployment. You must create a
new deployment (p. 493) or revise the deployment (p. 502) to modify the components that run on
the core devices that received the canceled deployment.
To cancel a deployment (AWS CLI)
1. Run the following command to find the ID of the latest deployment revision for a target. The latest
revision is the only deployment that can be active for a target, because previous deployments cancel
when you create a new revision. Replace targetArn with the ARN of the target AWS IoT thing or
thing group.
aws greengrassv2 list-deployments --target-arn targetArn
The response contains a list with the latest deployment for the target. Copy the deploymentId
from the response to use in the next step.
2. Run the following command to cancel the deployment. Replace deploymentId with the ID from
the previous step.
aws greengrassv2 cancel-deployment --deployment-id deploymentId
If the operation succeeds, the deployment status changes to CANCELED.
Check deployment status
You can check the status of a deployment that you create in AWS IoT Greengrass. You can also check
the status of the AWS IoT jobs that roll out the deployment to each core device. While a deployment is
active, the AWS IoT job's status is IN_PROGRESS. After you create a new revision of a deployment, the
status of the previous revision's AWS IoT job changes to CANCELLED.
Topics
• Check deployment status (p. 505)
• Check device deployment status (p. 505)
504
AWS IoT Greengrass Developer Guide, Version 2
Check deployment status
Check deployment status
You can check the status of a deployment that you identify by its target or its ID.
To check deployment status by target (AWS CLI)
• Run the following command to retrieve the status of the latest deployment for a target. Replace
targetArn with the ARN of the AWS IoT thing or thing group that the deployment targets.
aws greengrassv2 list-deployments --target-arn targetArn
The response contains a list with the latest deployment for the target. This deployment object
includes the status of the deployment.
To check deployment status by ID (AWS CLI)
• Run the following command to retrieve the status of a deployment. Replace deploymentId with
the ID of the deployment to query.
aws greengrassv2 get-deployment --deployment-id deploymentId
The response contains the status of the deployment.
Check device deployment status
You can check the status of a deployment job that applies to an individual core device.
To check deployment job status (AWS CLI)
• Run the following command to retrieve the status of all deployment jobs for a core device. Replace
coreDeviceName with the name of the core device to query.
aws greengrassv2 list-effective-deployments --core-device-thing-name coreDeviceName
The response contains the list of deployment jobs for the core device. You can identify the job for a
deployment by the jobs deploymentId or targetArn. Each deployment job contains the status of
the job on the core device.
505
AWS IoT Greengrass Developer Guide, Version 2
Monitoring tools
Logging and monitoring in AWS IoT
Greengrass
Monitoring is an important part of maintaining the reliability, availability, and performance of AWS
IoT Greengrass and your AWS solutions. You should collect monitoring data from all parts of your
AWS solution so that you can more easily debug a multi-point failure, if one occurs. Before you start
monitoring AWS IoT Greengrass, you should create a monitoring plan that includes answers to the
following questions:
• What are your monitoring goals?
• Which resources will you monitor?
• How often will you monitor these resources?
• Which monitoring tools will you use?
• Who will perform the monitoring tasks?
• Who should be notified when something goes wrong?
Topics
• Monitoring tools (p. 506)
• Monitor AWS IoT Greengrass logs (p. 506)
• Log AWS IoT Greengrass V2 API calls with AWS CloudTrail (p. 513)
• Gather system health telemetry data from AWS IoT Greengrass core devices (p. 515)
• Check Greengrass core device status (p. 521)
Monitoring tools
AWS provides tools that you can use to monitor AWS IoT Greengrass. You can configure some of these
tools to do the monitoring for you. Some of the tools require manual intervention. We recommend that
you automate monitoring tasks as much as possible.
You can use the following automated monitoring tools to monitor AWS IoT Greengrass and report issues:
• Amazon CloudWatch Logs – Monitor, store, and access your log files from AWS CloudTrail or other
sources. For more information, see Monitoring log files in the Amazon CloudWatch User Guide.
• AWS CloudTrail Log Monitoring – Share log files between accounts, monitor CloudTrail log files in real
time by sending them to CloudWatch Logs, write log processing applications in Java, and validate that
your log files have not changed after delivery by CloudTrail. For more information, see Working with
CloudTrail log files in the AWS CloudTrail User Guide.
• Greengrass system health telemetry – Subscribe to receive telemetry data sent from the Greengrass
core. For more information, see the section called “Gather system health telemetry data” (p. 515).
• Fleet status service – Use the fleet status API operations to check the status of core devices and their
Greengrass components. You can also view fleet status information in the AWS IoT Greengrass console.
For more information, see Check Greengrass core device status (p. 521).
Monitor AWS IoT Greengrass logs
AWS IoT Greengrass consists of the cloud service and the AWS IoT Greengrass Core software. The AWS
IoT Greengrass Core software can write logs to Amazon CloudWatch Logs and to the core device's local
506
AWS IoT Greengrass Developer Guide, Version 2
Access file system logs
file system. Greengrass components that run on the core device can also write logs to CloudWatch
Logs and the local file system. You can use logs to monitor events and troubleshoot issues. All AWS IoT
Greengrass log entries include a timestamp, log level, and information about the event.
By default, the AWS IoT Greengrass Core software writes logs to only the local file system. You can view
file system logs in real time, so you can debug Greengrass components that you develop and deploy.
You can also configure a core device to write logs to CloudWatch Logs, so you can troubleshoot the core
device without access to the local file system. For more information, see Enable logging to CloudWatch
Logs (p. 510).
Topics
• Access file system logs (p. 507)
• Access CloudWatch Logs (p. 509)
• Access system service logs (p. 510)
• Enable logging to CloudWatch Logs (p. 510)
• Configure logging for AWS IoT Greengrass (p. 511)
• AWS CloudTrail logs (p. 512)
Access file system logs
The AWS IoT Greengrass Core software stores logs in the /greengrass/v2/logs folder on a core
device, where /greengrass/v2 is the path to the AWS IoT Greengrass root folder. The logs folder has
the following structure.
/greengrass/v2
### logs
### greengrass.log
### greengrass_2021_09_14_15_0.log
### ComponentName.log
### ComponentName_2021_09_14_15_0.log
### main.log
• greengrass.log – The AWS IoT Greengrass Core software log file. Use this log file to view real-
time information about components and deployments. This log file includes logs for the Greengrass
nucleus, which is the core of the AWS IoT Greengrass Core software, and plugin components, such as
log manager (p. 273) and secret manager (p. 374).
• ComponentName.log – Greengrass component log files. Use component log files to view real-time
information about a Greengrass component that runs on the core device. Generic components and
Lambda components write standard output (stdout) and standard error (stderr) to these log files.
• main.log – The log file for the main service that handles component lifecycles. This log file will
always be empty.
For more information about the differences between plugin, generic, and Lambda components, see
Component types (p. 441).
The following considerations apply when you use file system logs:
• Root user permissions
You must have root permissions to read AWS IoT Greengrass logs on the file system.
• Log file rotation
The AWS IoT Greengrass Core software rotates log files every hour or when they exceed a file size
limit. Rotated log files contain a timestamp in their file name. For example, a rotated AWS IoT
507
AWS IoT Greengrass Developer Guide, Version 2
Access file system logs
Greengrass Core software log file might be named greengrass_2021_09_14_15_0.log. The
default file size limit is 1,024 KB (1 MB). You can configure the file size limit on the Greengrass nucleus
component (p. 181).
• Log file deletion
The AWS IoT Greengrass Core software cleans up earlier log files when the size of AWS IoT Greengrass
Core software log files or Greengrass component log files, including rotated log files, exceeds
a disk space limit. The default disk space limit for the AWS IoT Greengrass Core software log
and each component log is 10,240 KB (10 MB). You can configure the AWS IoT Greengrass Core
software log disk space limit on the Greengrass nucleus component (p. 181) or the log manager
component (p. 273). You can configure each component's log disk space limit on the log manager
component (p. 273).
To view the AWS IoT Greengrass Core software log file
• Run the following command to view the log file in real time. Replace /greengrass/v2 with the
path to the AWS IoT Greengrass root folder.
Linux or Unix
sudo tail -f /greengrass/v2/logs/greengrass.log
Windows Command Prompt (CMD)
type C:\greengrass\v2\logs\com.example.HelloWorld.log
The type command writes the file's contents to the terminal. Run this command multiple times
to observe changes in the file.
PowerShell
gc C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
To view the log file for a component
• Run the following command to view the log file in real time. Replace /greengrass/v2
or C:\greengrass\v2 with the path to the AWS IoT Greengrass root folder, and replace
com.example.HelloWorld with the name of the component.
Linux or Unix
sudo tail -f /greengrass/v2/logs/com.example.HelloWorld.log
PowerShell
gc C:\greengrass\v2\logs\com.example.HelloWorld.log -Tail 10 -Wait
You can also use the logs command of the Greengrass CLI (p. 225) to analyze Greengrass logs on a
core device. To use the logs command, you must configure the Greengrass nucleus (p. 181) to output
JSON format log files. For more information, see Greengrass Command Line Interface (p. 428) and
logs (p. 436).
508
AWS IoT Greengrass Developer Guide, Version 2
Access CloudWatch Logs
Access CloudWatch Logs
You can deploy the log manager component (p. 273) to configure the core device to write to CloudWatch
Logs. For more information, see Enable logging to CloudWatch Logs (p. 510). Then, you can view logs
on the Logs page of the Amazon CloudWatch console or using the CloudWatch Logs API.
Log group name
/aws/greengrass/componentType/region/componentName
The log group name uses the following variables:
• componentType – The type of the component, which can be one of the following:
• GreengrassSystemComponent – The component is part of the Greengrass nucleus (p. 181).
This log group includes logs for plugin components, which run in the same JVM as the
Greengrass nucleus.
• UserComponent – The component isn't part of the Greengrass nucleus. This log group includes
logs for generic components, Lambda components, and other applications on the device.
For more information, see Component types (p. 441).
• region – The AWS Region that the core device uses.
• componentName – The name of the component. For system logs, this value is System.
Log stream name
/date/thing/thingName
The log stream name uses the following variables:
• date – The date of the log, such as 2020/12/15. The log manager component uses the yyyy/
MM/dd format.
• thingName – The name of the core device.
Note
If a thing name contains a colon (:), the log manager replaces the colon with a plus (+).
The following considerations apply when you use the log manager component to write to CloudWatch
Logs:
• Log delays
The log manager component writes logs from only rotated log files. By default, the AWS IoT
Greengrass Core software rotates log files every hour or after they are 1,024 KB. As a result, the log
manager component uploads logs only after the AWS IoT Greengrass Core software or a Greengrass
component writes over 1,024 KB worth of logs. You can configure a lower log file size limit to cause
log files to rotate more often. This causes the log manager component to upload logs to CloudWatch
Logs more frequently.
The log manager component also uploads new logs periodically. By default, the log manager
component uploads new logs every 5 minutes. You can configure a lower upload interval, so the log
manager component uploads logs to CloudWatch Logs more frequently.
If you need to observe logs in real time, consider using file system logs (p. 507).
• Clock skew
The log manager component uses the standard Signature Version 4 signing process to create API
requests to CloudWatch Logs. If the system time on a core device is out of sync by more than 15
509
AWS IoT Greengrass Developer Guide, Version 2
Access system service logs
minutes, then CloudWatch Logs rejects the requests. For more information, see Signature Version 4
signing process in the AWS General Reference.
Access system service logs
If you configure the AWS IoT Greengrass Core software as a system service (p. 158), you can view system
service logs to troubleshoot issues, such as the software failing to start.
To view system service logs (CLI)
• Run the following command to view AWS IoT Greengrass Core software system service logs.
Linux or Unix (systemd)
sudo journalctl -u greengrass.service
Windows Command Prompt (CMD)
type C:\greengrass\v2\logs\greengrass.wrapper.log
PowerShell
gc C:\greengrass\v2\logs\greengrass.wrapper.log
On Windows devices, you can also use the Event Viewer application to view system service logs.
To view Windows service logs (Event Viewer)
1. Open the Event Viewer application.
2. Select Windows Logs to expand it.
3. Choose Application to view application service logs.
4. Find and open event logs whose Source is greengrass.
Enable logging to CloudWatch Logs
You can deploy the log manager component (p. 273) to configure a core device to write logs to
CloudWatch Logs. You can enable CloudWatch Logs for AWS IoT Greengrass Core software logs, and you
can enable CloudWatch Logs for specific Greengrass components.
Note
The Greengrass core device's token exchange role must allow the core device to write to
CloudWatch Logs, as shown in the following example IAM policy. If you installed the AWS IoT
Greengrass Core software with automatic resource provisioning (p. 69), your core device has
these permissions.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
510
AWS IoT Greengrass Developer Guide, Version 2
Configure logging for AWS IoT Greengrass
"logs:PutLogEvents",
"logs:DescribeLogStreams"
],
"Effect": "Allow",
"Resource": "arn:aws:logs:*:*:*"
}
]
}
To configure a core device to write AWS IoT Greengrass Core software logs to CloudWatch Logs, create a
deployment (p. 493) that specifies a configuration update that sets uploadToCloudWatch to true for
the aws.greengrass.LogManager component. AWS IoT Greengrass Core software logs include logs
for the Greengrass nucleus (p. 181) and plugin components (p. 441).
{
"logsUploaderConfiguration": {
"systemLogsConfiguration": {
"uploadToCloudWatch": "true"
}
}
}
To configure a core device to write a Greengrass component's logs to CloudWatch Logs, create a
deployment (p. 493) that specifies a configuration update that adds the component to the list of
component logging configurations. When you add a component to this list, the log manager component
writes its logs to CloudWatch Logs. Component logs include logs for generic components and Lambda
components (p. 441).
{
"logsUploaderConfiguration": {
"componentLogsConfiguration": [
{
"componentName": "com.example.HelloWorld"
}
]
}
}
When you deploy the log manager component, you can also configure disk space limits and whether the
core device deletes log files after writing them to CloudWatch Logs. For more information, see Configure
logging for AWS IoT Greengrass (p. 511).
Configure logging for AWS IoT Greengrass
You can configure the following options to customize logging for Greengrass core devices. To configure
these options, create a deployment (p. 493) that specifies a configuration update to the Greengrass
nucleus or log manager components.
• Writing logs to CloudWatch Logs
To remotely troubleshoot core devices, you can configure core devices to write AWS IoT Greengrass
Core software and component logs to CloudWatch Logs. To do so, deploy and configure the
log manager component (p. 273). For more information, see Enable logging to CloudWatch
Logs (p. 510).
• Deleting uploaded log files
To reduce disk space usage, you can configure core devices to delete log files after writing
the log files to CloudWatch Logs. For more information, see the log manager component's
511
AWS IoT Greengrass Developer Guide, Version 2
AWS CloudTrail logs
deleteLogFileAfterCloudUpload parameter, which you can specify for AWS IoT Greengrass Core
software logs (p. 277) and component logs (p. 278).
• Log disk space limits
To limit disk space usage, you can configure the maximum disk space for each log, including its
rotated log files, on a core device. For example, you can configure the maximum combined disk
space for greengrass.log and rotated greengrass.log files. For more information, see the
Greengrass nucleus component's logging.totalLogsSizeKB parameter and the log manager
component's diskSpaceLimit parameter, which you can specify for AWS IoT Greengrass Core
software logs (p. 277) and component logs (p. 278).
• Log file size limit
You can configure the maximum file size for each log file. After a log file exceeds this file size limit,
the AWS IoT Greengrass Core software creates a new log file. The log manager component (p. 273)
writes only rotated log files to CloudWatch Logs, so you can specify a lower file size limit to write logs
to CloudWatch Logs more frequently. For more information, see the Greengrass nucleus component's
log file size limit parameter (p. 187) (logging.fileSizeKB).
• Minimum log levels
You can configure the minimum log level that the Greengrass nucleus component writes to file
system logs. For example, you might specify DEBUG level logs to help with troubleshooting, or you
might specify ERROR level logs to reduce the amount of logs that a core device creates. For more
information, see the Greengrass nucleus component's log level parameter (p. 186) (logging.level).
You can also configure the minimum log level that the log manager component writes to CloudWatch
Logs. For example, you might specify a higher log level to reduce logging costs. For more information,
see the log manager component's minimumLogLevel parameter, which you can specify for AWS IoT
Greengrass Core software logs (p. 277) and component logs (p. 278).
• Interval to check for logs to write to CloudWatch Logs
To increase or decrease how frequently the log manager component writes logs to CloudWatch
Logs, you can configure the interval where it checks for new log files to write. For example, you
might specify a lower interval to view logs in CloudWatch Logs sooner than you would with the
default 5-minute interval. You might specify a higher interval to reduce costs, because the log
manager component batches log files into fewer requests. For more information, see the log manager
component's upload interval parameter (p. 279) (periodicUploadIntervalSec).
• Log format
You can choose whether the AWS IoT Greengrass Core software writes logs in text or JSON format.
Choose text format if you read logs, or choose JSON format if you use an application to read or parse
logs. For more information, see the Greengrass nucleus component's log format parameter (p. 186)
(logging.format).
• Local file system logs folder
You can change the logs folder from /greengrass/v2/logs to another folder on the core device.
For more information, see the Greengrass nucleus component's output directory parameter (p. 186)
(logging.outputDirectory).
AWS CloudTrail logs
AWS IoT Greengrass integrates with AWS CloudTrail, a service that provides a record of actions taken by
a user, role, or AWS service in AWS IoT Greengrass. For more information, see Log AWS IoT Greengrass
V2 API calls with AWS CloudTrail (p. 513).
512
AWS IoT Greengrass Developer Guide, Version 2
Log API calls with CloudTrail
Log AWS IoT Greengrass V2 API calls with AWS
CloudTrail
AWS IoT Greengrass V2 is integrated with AWS CloudTrail, a service that provides a record of actions
taken by a user, role, or an AWS service in AWS IoT Greengrass Version 2. CloudTrail captures all API calls
for AWS IoT Greengrass as events. The calls that are captured include calls from the AWS IoT Greengrass
console and code calls to the AWS IoT Greengrass API operations.
If you create a trail, you can enable continuous delivery of CloudTrail events to an S3 bucket, including
events for AWS IoT Greengrass. If you don't configure a trail, you can still view the most recent events
in the CloudTrail console in Event history. Using the information collected by CloudTrail, you can
determine the request that was made to AWS IoT Greengrass, the IP address from which the request was
made, who made the request, when it was made, and additional details.
For more information about CloudTrail, see the AWS CloudTrail User Guide.
AWS IoT Greengrass V2 information in CloudTrail
CloudTrail is enabled on your AWS account when you create the account. When activity occurs in AWS IoT
Greengrass, that activity is recorded in a CloudTrail event along with other AWS service events in Event
history. You can view, search, and download recent events in your AWS account. For more information,
see Viewing events with CloudTrail Event history.
For an ongoing record of events in your AWS account, including events for AWS IoT Greengrass, create
a trail. A trail enables CloudTrail to deliver log files to an S3 bucket. By default, when you create a trail
in the console, the trail applies to all AWS Regions. The trail logs events from all Regions in the AWS
partition and delivers the log files to the S3 bucket that you specify. Additionally, you can configure
other AWS services to further analyze and act upon the event data collected in CloudTrail logs. For more
information, see the following:
• Overview for creating a trail
• CloudTrail supported services and integrations
• Configuring Amazon SNS notifications for CloudTrail
• Receiving CloudTrail log files from multiple regions and Receiving CloudTrail log files from multiple
accounts
All AWS IoT Greengrass V2 actions are logged by CloudTrail and are documented in the AWS
IoT Greengrass V2 API Reference. For example, calls to the CreateComponentVersion,
CreateDeployment and CancelDeployment actions generate entries in the CloudTrail log files.
Every event or log entry contains information about who generated the request. The identity
information helps you determine the following:
• Whether the request was made with root or AWS Identity and Access Management (IAM) user
credentials.
• Whether the request was made with temporary security credentials for a role or federated user.
• Whether the request was made by another AWS service.
For more information, see the CloudTrail userIdentity element.
513
AWS IoT Greengrass Developer Guide, Version 2
Understanding AWS IoT Greengrass V2 log file entries
Understanding AWS IoT Greengrass V2 log file entries
A trail is a configuration that enables delivery of events as log files to an S3 bucket that you specify.
CloudTrail log files contain one or more log entries. An event represents a single request from any source.
It includes information about the requested action, the date and time of the action, request parameters,
and so on. CloudTrail log files aren't an ordered stack trace of the public API calls, so they don't appear in
any specific order.
The following example shows a CloudTrail log entry that demonstrates the CreateDeployment action.
{
"eventVersion": "1.08",
"userIdentity": {
"type": "IAMUser",
"principalId": "AIDACKCEVSQ6C2EXAMPLE",
"arn": "arn:aws:iam::123456789012:user/Administrator",
"accountId": "123456789012",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"userName": "Administrator"
},
"eventTime": "2021-01-06T02:38:05Z",
"eventSource": "greengrass.amazonaws.com",
"eventName": "CreateDeployment",
"awsRegion": "us-west-2",
"sourceIPAddress": "203.0.113.0",
"userAgent": "aws-cli/2.1.9 Python/3.7.9 Windows/10 exe/AMD64 prompt/off command/
greengrassv2.create-deployment",
"requestParameters": {
"deploymentPolicies": {
"failureHandlingPolicy": "DO_NOTHING",
"componentUpdatePolicy": {
"timeoutInSeconds": 60,
"action": "NOTIFY_COMPONENTS"
},
"configurationValidationPolicy": {
"timeoutInSeconds": 60
}
},
"deploymentName": "Deployment for MyGreengrassCoreGroup",
"components": {
"aws.greengrass.Cli": {
"componentVersion": "2.0.3"
}
},
"iotJobConfiguration": {},
"targetArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/MyGreengrassCoreGroup"
},
"responseElements": {
"iotJobArn": "arn:aws:iot:us-west-2:123456789012:job/fdfeba1d-ac6d-44ef-
ab28-54f684ea578d",
"iotJobId": "fdfeba1d-ac6d-44ef-ab28-54f684ea578d",
"deploymentId": "4196dddc-0a21-4c54-a985-66a525f6946e"
},
"requestID": "311b9529-4aad-42ac-8408-c06c6fec79a9",
"eventID": "c0f3aa2c-af22-48c1-8161-bad4a2ab1841",
"readOnly": false,
"eventType": "AwsApiCall",
"managementEvent": true,
"eventCategory": "Management",
"recipientAccountId": "123456789012"
}
514
AWS IoT Greengrass Developer Guide, Version 2
Gather system health telemetry data
Gather system health telemetry data from AWS
IoT Greengrass core devices
System health telemetry data is diagnostic data that can help you monitor the performance of critical
operations on your Greengrass core devices. You can create projects and applications to retrieve,
analyze, transform, and report telemetry data from your edge devices. Domain experts, such as process
engineers, can use these applications to gain insights into fleet health.
You can use the following methods to gather telemetry data from your Greengrass core devices:
• Nucleus emitter component—The nucleus emitter component
(aws.greengrass.telemetry.NucleusEmitter) on your Greengrass core device publishes
telemetry data to the $local/greengrass/telemetry topic by default. You can use the data
that is published to this topic to act locally on your core device, even when your device has limited
connectivity to the cloud. Optionally, you can also configure the component to publish telemetry data
to an AWS IoT Core MQTT topic of your choice.
You must deploy the nucleus emitter component to your core device to publish telemetry data. There
are no costs associated with publishing telemetry data to the local topic. However, the use of an MQTT
topic to publish data to the cloud is subject to AWS IoT Core pricing.
• Telemetry agent—The telemetry agent on Greengrass core devices collects local telemetry data and
publishes it to Amazon EventBridge without requiring any customer interaction. Core devices publish
telemetry data to EventBridge on a best effort basis. For example, core devices might fail to deliver
telemetry data while offline.
The telemetry agent feature is enabled by default for all Greengrass core devices. You automatically
start to receive data as soon as you set up a Greengrass core device. Aside from your data link costs,
the data transfer from the core device to AWS IoT Core is without charge. This is because the agent
publishes to an AWS reserved topic. However, depending on your use case, you might incur costs when
you receive or process the data.
Note
Amazon EventBridge is an event bus service that you can use to connect your applications
with data from a variety of sources, such as Greengrass core devices. For more information,
see What is Amazon EventBridge? in the Amazon EventBridge User Guide.
To ensure that the the AWS IoT Greengrass Core software functions properly, AWS IoT Greengrass uses
the data for development and quality improvement purposes. This feature also helps inform new and
enhanced edge capabilities. AWS IoT Greengrass retains telemetry data for up to seven days.
This section describes how to configure and use the telemetry agent. For information about configuring
the nucleus emitter component, see Nucleus telemetry emitter (p. 368).
Topics
• Telemetry metrics (p. 515)
• Configure telemetry agent settings (p. 517)
• Subscribe to telemetry data in EventBridge (p. 517)
Telemetry metrics
The following table describes the metrics that are published by the telemetry agent.
515
AWS IoT Greengrass Developer Guide, Version 2
Telemetry metrics
Name Description Source
SystemMemUsage The amount of memory System
currently in use by all
applications on the Greengrass
core device, including the
operating system.
CpuUsage The amount of CPU currently System
in use by all applications on
the Greengrass core device,
including the operating system.
TotalNumberOfFDs The number of file descriptors System
stored by the operating system
of the Greengrass core device.
One file descriptor uniquely
identifies one open file.
NumberOfComponentsRunning The number of components that Greengrass nucleus
are running on the Greengrass
core device.
NumberOfComponentsErrored The number of components Greengrass nucleus
that are in error state on the
Greengrass core device.
NumberOfComponentsInstalledThe number of components that Greengrass nucleus
are installed on the Greengrass
core device.
NumberOfComponentsStarting The number of components that Greengrass nucleus
are starting on the Greengrass
core device.
NumberOfComponentsNew The number of components that Greengrass nucleus
are new on the Greengrass core
device.
NumberOfComponentsStopping The number of components that Greengrass nucleus
are stopping on the Greengrass
core device.
NumberOfComponentsFinished The number of components that Greengrass nucleus
are finished on the Greengrass
core device.
NumberOfComponentsBroken The number of components that Greengrass nucleus
are broken on the Greengrass
core device.
NumberOfComponentsStatelessThe number of components that Greengrass nucleus
are stateless on the Greengrass
core device.
516
AWS IoT Greengrass Developer Guide, Version 2
Configure telemetry agent settings
Configure telemetry agent settings
The telemetry agent uses the following default settings:
• The telemetry agent aggregates telemetry data every hour.
• The telemetry agent publishes a telemetry message every 24 hours.
The telemetry agent publishes data using the MQTT protocol with a quality of service (QoS) level of 0,
which means that it doesn't confirm delivery or retry publishing attempts. Telemetry messages share an
MQTT connection with other messages for subscriptions destined for AWS IoT Core.
Aside from your data link costs, the data transfer from the core to AWS IoT Core is without charge. This is
because the agent publishes to an AWS reserved topic. However, depending on your use case, you might
incur costs when you receive or process the data.
You can enable or disable the telemetry agent feature for each Greengrass core device. You can also
configure the intervals over which the core device aggregates and publishes data. To configure telemetry,
customize the telemetry configuration parameter (p. 187) when you deploy the Greengrass nucleus
component (p. 181).
Subscribe to telemetry data in EventBridge
You can create rules in Amazon EventBridge that define how to process telemetry data published from
the telemetry agent on the Greengrass core device. When EventBridge receives the data, it invokes the
target actions defined in your rules. For example, you can create event rules that send notifications, store
event information, take corrective action, or invoke other events.
Telemetry events
Telemetry events use the following format.
{
"version": "0",
"id": "a09d303e-2f6e-3d3c-a693-8e33f4fe3955",
"detail-type": "Greengrass Telemetry Data",
"source": "aws.greengrass",
"account": "123456789012",
"time": "2020-11-30T20:45:53Z",
"region": "us-east-1",
"resources": [],
"detail": {
"ThingName": "MyGreengrassCore",
"Schema": "2020-07-30",
"ADP": [
{
"TS": 1602186483234,
"NS": "SystemMetrics",
"M": [
{
"N": "TotalNumberOfFDs",
"Sum": 6447.0,
"U": "Count"
},
{
"N": "CpuUsage",
"Sum": 15.458333333333332,
"U": "Percent"
},
{
"N": "SystemMemUsage",
517
AWS IoT Greengrass Developer Guide, Version 2
Subscribe to telemetry data in EventBridge
"Sum": 10201.0,
"U": "Megabytes"
}
]
},
{
"TS": 1602186483234,
"NS": "GreengrassComponents",
"M": [
{
"N": "NumberOfComponentsStopping",
"Sum": 0.0,
"U": "Count"
},
{
"N": "NumberOfComponentsStarting",
"Sum": 0.0,
"U": "Count"
},
{
"N": "NumberOfComponentsBroken",
"Sum": 0.0,
"U": "Count"
},
{
"N": "NumberOfComponentsFinished",
"Sum": 1.0,
"U": "Count"
},
{
"N": "NumberOfComponentsInstalled",
"Sum": 0.0,
"U": "Count"
},
{
"N": "NumberOfComponentsRunning",
"Sum": 7.0,
"U": "Count"
},
{
"N": "NumberOfComponentsNew",
"Sum": 0.0,
"U": "Count"
},
{
"N": "NumberOfComponentsErrored",
"Sum": 0.0,
"U": "Count"
},
{
"N": "NumberOfComponentsStateless",
"Sum": 0.0,
"U": "Count"
}
]
}
]
}
}
The ADP array contains a list of aggregated data points that have the following properties:
TS
The timestamp of when the data was gathered.
518
AWS IoT Greengrass Developer Guide, Version 2
Subscribe to telemetry data in EventBridge
NS
The metric namespace.
M
The list of metrics. A metric contains the following properties:
N
The name of the metric.
Sum
The aggregated metric value. The telemetry agent adds new values to the previous total, so
the sum is a value that increases constantly. You can use the timestamp to find the value of a
specific aggregation. For example, to find the latest aggregated value, subtract the previous
timestamped value from the latest timestamped value.
U
The unit of the metric value.
For more information about each metric, see Telemetry metrics (p. 515).
Prerequisites to create EventBridge rules
Before you create an EventBridge rule for AWS IoT Greengrass, you should do the following:
• Familiarize yourself with events, rules, and targets in EventBridge.
• Create and configure the targets invoked by your EventBridge rules. Rules can invoke many types of
targets, such as Amazon Kinesis streams, AWS Lambda functions, Amazon SNS topics, and Amazon
SQS queues.
Your EventBridge rule, and the associated targets must be in the AWS Region where you created your
Greengrass resources. For more information, see Service endpoints and quotas in the AWS General
Reference.
For more information, see What is Amazon EventBridge? and Getting started with Amazon EventBridge
in the Amazon EventBridge User Guide.
Create an event rule to get telemetry data (console)
Use the following steps to use the AWS Management Console to create an EventBridge rule that receives
telemetry data published by the Greengrass core device. This allows web servers, email addresses, and
other topic subscribers to respond to the event. For more information, see Creating a EventBridge rule
that triggers on an event from an AWS resource in the Amazon EventBridge User Guide.
1. Open the Amazon EventBridge console, and choose Create rule.
2. Under Name and description, enter a name and description for the rule.
3. Under Define pattern, configure the rule pattern.
a. Choose Event pattern.
b. Choose Pre-defined pattern by service.
c. For Service provider, choose AWS.
d. For Service name, choose Greengrass.
519
AWS IoT Greengrass Developer Guide, Version 2
Subscribe to telemetry data in EventBridge
e. For Event type, select Greengrass Telemetry Data.
4. Under Select event bus, keep the default event bus options.
5. Under Select targets, configure your target. The following example uses an Amazon SQS queue, but
you can configure other target types.
a. For Target, choose SQS queue.
b. For Queue*, choose your target queue.
6. Under Tags - optional, define tags for the rule or leave the fields empty.
7. Choose Create.
Create an event rule to get telemetry data (CLI)
Use the following steps to use the AWS CLI to create an EventBridge rule that receives telemetry
data published by Greengrass core devices. This allows web servers, email addresses, and other topic
subscribers to respond to the event.
1. Create the rule.
• Replace thing-name with the thing name of the core device.
Linux or Unix
aws events put-rule \
--name MyGreengrassTelemetryEventRule \
--event-pattern "{\"source\": [\"aws.greengrass\"], \"detail\": {\"ThingName\":
[\"thing-name\"]}}"
Windows Command Prompt (CMD)
aws events put-rule ^
--name MyGreengrassTelemetryEventRule ^
--event-pattern "{\"source\": [\"aws.greengrass\"], \"detail\": {\"ThingName\":
[\"thing-name\"]}}"
PowerShell
aws events put-rule `
--name MyGreengrassTelemetryEventRule `
--event-pattern "{\"source\": [\"aws.greengrass\"], \"detail\": {\"ThingName\":
[\"thing-name\"]}}"
Properties that are omitted from the pattern are ignored.
2. Add the topic as a rule target. The following example uses Amazon SQS but you can configure other
target types.
• Replace queue-arn with the ARN of your Amazon SQS queue.
Linux or Unix
aws events put-targets \
--rule MyGreengrassTelemetryEventRule \
--targets "Id"="1","Arn"="queue-arn"
520
AWS IoT Greengrass Developer Guide, Version 2
Check core device status
Windows Command Prompt (CMD)
aws events put-targets ^
--rule MyGreengrassTelemetryEventRule ^
--targets "Id"="1","Arn"="queue-arn"
PowerShell
aws events put-targets `
--rule MyGreengrassTelemetryEventRule `
--targets "Id"="1","Arn"="queue-arn"
Note
To allow Amazon EventBridge to invoke your target queue, you must add a resource-based
policy to your topic. For more information, see Amazon SQS permissions in the Amazon
EventBridge User Guide.
For more information, see Events and event patterns in EventBridge in the Amazon EventBridge User
Guide.
Check Greengrass core device status
Greengrass core devices report the status of their software components to AWS IoT Greengrass. You
can check the health summary of each device, and you can check the status of each component on each
device.
Core devices have the following health statuses:
• HEALTHY – The AWS IoT Greengrass Core software and all components run without issue on the core
device.
• UNHEALTHY – The AWS IoT Greengrass Core software or a component is in an error state on the core
device.
Note
AWS IoT Greengrass relies on individual devices to send status updates to the AWS Cloud. If the
AWS IoT Greengrass Core software isn't running on the device, or if device isn't connected to
the AWS Cloud, then the reported status of that device might not reflect its current status. The
status timestamp indicates when the device status was last updated.
Topics
• Check health of a core device (p. 521)
• Check health of a core device group (p. 522)
• Check core device component status (p. 522)
Check health of a core device
You can check the status of individual core devices.
521
AWS IoT Greengrass Developer Guide, Version 2
Check health of a core device group
To check the status of a core device (AWS CLI)
• Run the following command to retrieve the status of a device. Replace coreDeviceName with the
name of the core device to query.
aws greengrassv2 get-core-device --core-device-thing-name coreDeviceName
The response contains information about the core device, including its status.
Check health of a core device group
You can check the status of a group of core devices (a thing group).
To check the status of a group of devices (AWS CLI)
• Run the following command to retrieve the status of multiple core devices. Replace the ARN in the
command with the ARN of the thing group to query.
aws greengrassv2 list-core-devices --thing-group-arn "arn:aws:iot:region:account-
id:thinggroup/thingGroupName"
The response contains the list of core devices in the thing group. Each entry in the list contains the
status of the core device.
Check core device component status
You can check the status, such as lifecycle state, of the software components on a core device. For more
information about component lifecycle states, see Develop AWS IoT Greengrass components (p. 440).
To check the status of components on a core device (AWS CLI)
• Run the following command to retrieve the status of the components on a core device. Replace
coreDeviceName with the name of the core device to query.
aws greengrassv2 list-installed-components --core-device-thing-name coreDeviceName
The response contains the list of components that run on the core device. Each entry in the list
contains the lifecycle state of the component.
522
AWS IoT Greengrass Developer Guide, Version 2
Requirements
Run AWS Lambda functions
Note
AWS IoT Greengrass doesn't currently support this feature on Windows core devices.
You can import AWS Lambda functions as components that run on AWS IoT Greengrass core devices. You
might want to do this in the following cases:
• You have application code in Lambda functions that you want to deploy to core devices.
• You have AWS IoT Greengrass V1 applications that you want to run on AWS IoT Greengrass V2 core
devices. For more information, see Run AWS IoT Greengrass V1 applications on AWS IoT Greengrass
V2 (p. 10).
Lambda functions include dependencies on the following components. You don't need to define these
components as dependencies when you import the function. When you deploy the Lambda function
component, the deployment includes these Lambda component dependencies.
• The Lambda launcher component (p. 252) (aws.greengrass.LambdaLauncher) handles processes
and environment configuration.
• The Lambda manager component (p. 255) (aws.greengrass.LambdaManager) handles interprocess
communication and scaling.
• The Lambda runtimes component (p. 258) (aws.greengrass.LambdaRuntimes) provides artifacts
for each supported Lambda runtime.
Topics
• Requirements (p. 523)
• Configure Lambda function lifecycle (p. 524)
• Configure Lambda function containerization (p. 524)
• Import a Lambda function as a component (console) (p. 526)
• Import a Lambda function as a component (AWS CLI) (p. 530)
Requirements
Your core devices and Lambda functions must meet the following requirements for you to run the
functions on the AWS IoT Greengrass Core software:
• Your core device must meet the requirements to run Lambda functions. If you want the core device
to run containerized Lambda functions, the device must meet the requirements to do so. For more
information, see Lambda function requirements (p. 64).
• You must install the programming languages that the Lambda function uses on your core devices.
Tip
You can create a component that installs the programming language, and then specify that
component as a dependency of your Lambda function component.
• Your Lambda function must use one of the following runtimes:
• Python 3.8 – python3.8
• Python 3.7 – python3.7
• Python 2.7 – python2.7 *
523
AWS IoT Greengrass Developer Guide, Version 2
Configure Lambda function lifecycle
• Java 8 – java8
• Node.js 12 – nodejs12.x
• Node.js 10 – nodejs10.x *
* You can run Lambda functions that use this runtime on AWS IoT Greengrass, but you can't create
them in AWS Lambda. For more information, see Runtime support policy in the AWS Lambda Developer
Guide.
Configure Lambda function lifecycle
The Greengrass Lambda function lifecycle determines when a function starts and how it creates and uses
containers. The lifecycle also determines how the AWS IoT Greengrass Core software retains variables
and preprocessing logic that are outside of the function handler.
AWS IoT Greengrass supports on-demand (default) and long-lived lifecycles:
• On-demand functions start when they are invoked and stop when there are no tasks left to run. Each
invocation of the function creates a separate container, also called a sandbox, to process invocations,
unless an existing container is available for reuse. Any of the containers might process data that you
send to the function.
Multiple invocations of an on-demand function can run simultaneously.
Variables and preprocessing logic that you define outside of the function handler are not retained
when new containers are created.
• Long-lived (or pinned) functions start when the AWS IoT Greengrass Core software starts and run in a
single container. The same container processes all data that you send to the function.
Multiple invocations are queued until the AWS IoT Greengrass Core software runs earlier invocations.
Variables and preprocessing logic that you define outside of the function handler are retained for
every invocation of the handler.
Use long-lived Lambda functions when you need to start doing work without any initial input. For
example, a long-lived function can load and start processing a machine learning model to be ready
when the function receives device data.
Note
Long-lived functions have timeouts that are associated with each invocation of their handler.
If you want to invoke code that runs indefinitely, you must start it outside of the handler.
Make sure that there's no blocking code outside of the handler that might prevent the
function from initializing.
These functions run unless the AWS IoT Greengrass Core software stops, such as during a
deployment or reboot. These functions won't run if the function encounters an uncaught
exception, exceeds its memory limits, or enters an error state, such as a handler timeout.
For more information about container reuse, see Understanding Container Reuse in AWS Lambda in the
AWS Compute Blog.
Configure Lambda function containerization
By default, Lambda functions run inside of an AWS IoT Greengrass container. Greengrass containers
provide isolation between your functions and the host. This isolation increases security for both the host
and the functions in the container.
524
AWS IoT Greengrass Developer Guide, Version 2
Configure Lambda function containerization
We recommend that you run Lambda functions in a Greengrass container, unless your use case requires
them to run without containerization. By running your Lambda functions in a Greengrass container, you
have more control over how you restrict access to resources.
You might run a Lambda function without containerization in the following cases:
• You want to run AWS IoT Greengrass on a device that doesn't support container mode. An example
would be if you wanted to use a special Linux distribution, or have an earlier kernel version that is out
of date.
• You want to run your Lambda function in another container environment with its own OverlayFS, but
encounter OverlayFS conflicts when you run in a Greengrass container.
• You need access to local resources with paths that can't be determined at deployment time, or whose
paths can change after deployment. An example of this resource would be a pluggable device.
• You have an earlier application that was written as a process, and you encounter issues when you run it
in a Greengrass container.
Containerization differences
Containerization Notes
Greengrass container • All AWS IoT Greengrass features are available
when you run a Lambda function in a
Greengrass container.
• Lambda functions that run in a Greengrass
container don't have access to the deployed
code of other Lambda functions, even if
they run with the same system group. In
other words, your Lambda functions run with
increased isolation from one another.
• Because the AWS IoT Greengrass Core software
runs all child processes in the same container as
the Lambda function, the child processes stop
when the Lambda function stops.
No container • The following features aren't available to non-
containerized Lambda functions:
• Lambda function memory limits.
• Local device and volume resources. You must
access these resources using their file paths
on the core device instead of as Lambda
function resources.
• If your non-containerized Lambda function
accesses a machine learning resource, you
must identify a resource owner and set access
permissions on the resource, not on the Lambda
function.
• Non-containerized Lambda functions have
read-only access to the deployed code of other
Lambda functions that run with the same
system group.
If you change the containerization for a Lambda function when you deploy it, the function might not
work as expected. If the Lambda function uses local resources that are no longer available with the new
containerization setting, deployment fails.
525
AWS IoT Greengrass Developer Guide, Version 2
Import a Lambda function as a component (console)
• When you change a Lambda function from running in a Greengrass container to running without
containerization, the function's memory limits are discarded. You must access the file system directly
instead of using attached local resources. You must remove any attached resources before you deploy
the Lambda function.
• When you change a Lambda function from running without containerization to running in a container,
your Lambda function loses direct access to the file system. You must define a memory limit for each
function or accept the default 16 MB memory limit. You can configure these settings for each Lambda
function when you deploy it.
To change containerization settings for a Lambda function component, set the value of the
containerMode configuration parameter to one of the following options when you deploy the
component.
• NoContainer – The component doesn't run in an isolated runtime environment.
• GreengrassContainer – The component runs in an isolated runtime environment inside the AWS
IoT Greengrass container.
For more information about how to deploy and configure components, see Deploy AWS IoT Greengrass
components to devices (p. 491) and Update component configurations (p. 500).
Import a Lambda function as a component
(console)
When you use the AWS IoT Greengrass console to create a Lambda function component, you import an
existing AWS Lambda function and then configure it to create a component that runs on your Greengrass
device.
Before you begin, review the requirements to run Lambda functions on Greengrass devices.
Tasks
• Step 1: Choose a Lambda function to import (p. 526)
• Step 2: Configure Lambda function parameters (p. 527)
• Step 3: (Optional) Specify supported platforms for the Lambda function (p. 528)
• Step 4: (Optional) Specify component dependencies for the Lambda function (p. 528)
• Step 5: (Optional) Run the Lambda function in a container (p. 529)
• Step 6: Create the Lambda function component (p. 530)
Step 1: Choose a Lambda function to import
1. In the AWS IoT Greengrass console navigation menu, choose Components.
2. On the Components page, choose Create component.
3. On the Create component page, under Component information, choose Import Lambda function.
4. In Lambda function, search for and choose the Lambda function that you want to import.
AWS IoT Greengrass creates the component with the name of the Lambda function.
5. In Lambda function version, choose the version to import. You can't choose Lambda aliases like
$LATEST.
526
AWS IoT Greengrass Developer Guide, Version 2
Step 2: Configure Lambda function parameters
AWS IoT Greengrass creates the component with the version of the Lambda function as a valid
semantic version. For example, if your function version is 3, the component version becomes 3.0.0.
Step 2: Configure Lambda function parameters
On the Create component page, under Lambda function configuration, configure the following
parameters to use to run the Lambda function.
1. (Optional) Add the list of event sources to which the Lambda function subscribes for work messages.
The Lambda function is called when it receives a message from an event source. You can subscribe
this function to local publish/subscribe messages and AWS IoT Core MQTT messages.
Under Event sources, do the following to add an event source:
a. For each event source that you add, specify the following options:
• Topic – The name of the topic to subscribe for messages.
• Type – The type of event source.
b. To add another event source, choose Add event source and repeat the previous step. To remove
an event source, choose Remove next to the event source that you want to remove.
2. For Timeout (seconds), enter the maximum amount of time in seconds that a non-pinned Lambda
function can run before it times out. The default is 3 seconds.
3. For Pinned, choose whether the Lambda function component is pinned. The default is True.
• A pinned (or long-lived) Lambda function starts when AWS IoT Greengrass starts and keeps
running in its own container.
• A non-pinned (or on-demand) Lambda function starts only when it receives a work item and exits
after it remains idle for a specified maximum idle time. If the function has multiple work items,
the AWS IoT Greengrass Core software creates multiple instances of the function.
4. (Optional) Under Additional parameters, set the following Lambda function parameters.
• Status timeout (seconds) – The interval in seconds at which the Lambda function component
sends status updates to the Lambda manager component. This parameter applies only to pinned
functions. The default is 60 seconds.
• Maximum queue size – The maximum size of the message queue for the Lambda function
component. The AWS IoT Greengrass Core software stores messages in a FIFO (first-in, first-
out) queue until it can run the Lambda function to consume each message. The default is 1,000
messages.
• Maximum number of instances – The maximum number of instances that a non-pinned Lambda
function can run at the same time. The default is 100 instances.
• Maximum idle time (seconds) – The maximum amount of time in seconds that a non-pinned
Lambda function can idle before the AWS IoT Greengrass Core software stops its process. The
default is 60 seconds.
• Encoding type – The type of payload that the Lambda function supports. Choose from the
following options:
• JSON
• Binary
The default is JSON.
5. (Optional) Specify the list of command line arguments to pass to the Lambda function when it runs.
a. Under Additional parameters, Process arguments, choose Add argument.
b. For each argument that you add, enter the argument that you want to pass to the function.
527
AWS IoT Greengrass Developer Guide, Version 2
Step 3: (Optional) Specify supported
platforms for the Lambda function
c. To remove an argument, choose Remove next to the argument that you want to remove.
6. (Optional) Specify the environment variables that are available to the Lambda function when it runs.
Environment variables enable you to store and update configuration settings without the need to
change function code.
a. Under Additional parameters, Environment variables, choose Add environment variable.
b. For each environment variable that you add, specify the following options:
• Key – The variable name.
• Value – The default value for this variable.
c. To remove an environment variable, choose Remove next to the environment variable that you
want to remove.
Step 3: (Optional) Specify supported platforms for
the Lambda function
All core devices have attributes for operating system and architecture. When you deploy the Lambda
function component, the AWS IoT Greengrass Core software compares the platform values that you
specify with the platform attributes on the core device to determine whether the Lambda function is
supported on that device.
Note
You can also specify custom platform attributes when you deploy the Greengrass
nucleus component to a core device. For more information, see the platform overrides
parameter (p. 188) of the Greengrass nucleus component (p. 181).
Under Lambda function configuration, Additional parameters, Platforms, do the following to specify
the platforms that this Lambda function supports.
1. For each platform, specify the following options:
• Operating system – The name of the operating system for the platform. Currently, the only
supported value is linux.
• Architecture – The processor architecture for the platform. Supported values are:
• amd64
• arm
• aarch64
• x86
2. To add another platform, choose Add platform and repeat the previous step. To remove a
supported platform, choose Remove next to the platform that you want to remove.
Step 4: (Optional) Specify component dependencies
for the Lambda function
Component dependencies identify additional AWS-provided components or custom components that
your function uses. When you deploy the Lambda function component, the deployment includes these
dependencies for your function to run.
Important
To import a Lambda function that you created to run on AWS IoT Greengrass V1, you
must define individual component dependencies for the features that your function uses,
such as subscriptions, secrets, and stream manager. Define these components as hard
528
AWS IoT Greengrass Developer Guide, Version 2
Step 5: (Optional) Run the Lambda function in a container
dependencies (p. 471) so that your Lambda function component restarts if the dependency
changes state. For more information, see Run V1 Lambda functions (p. 11).
Under Lambda function configuration, Additional parameters, Component dependencies, complete
the following steps to specify the component dependencies for your Lambda function.
1. Choose Add dependency.
2. For each component dependency that you add, specify the following options:
• Component name – The component name. For example, enter
aws.greengrass.StreamManager to include the stream manager component (p. 398).
• Version requirement – The npm-style semantic version constraint that identifies the compatible
versions of this component dependency. You can specify a single version or a range of versions.
For example, enter ^1.0.0 to specify that this Lambda function depends on any version in the
first major version of the stream manager component. For more information about semantic
version constraints, see the npm semver calculator.
• Type – The type of dependency. Choose from the following options:
• Hard – The Lambda function component restarts if the dependency changes state. This is the
default selection.
• Soft – The Lambda function component doesn't restart if the dependency changes state.
3. To remove a component dependency, choose Remove next to the component dependency
Step 5: (Optional) Run the Lambda function in a
container
By default, Lambda functions run in an isolated runtime environment inside the AWS IoT Greengrass
Core software. You can also choose to run the Lambda function as a process without any isolation (that
is, in No container mode).
Under Linux process configuration, for Isolation mode, choose from the following options to select the
containerization for your Lambda function:
• Greengrass container – The Lambda function runs in a container. This is the default selection.
• No container – The Lambda function runs as a process without any isolation.
If you run the Lambda function in a container, complete the following steps to configure the process
configuration for the Lambda function.
1. Configure the amount of memory and the system resources, such as volumes and devices, to make
available to the container.
Under Container parameters, do the following.
a. For Memory size, enter the memory size that you want to allocate to the container. You can
specify the memory size in MB or kB.
b. For Read-only sys folder, choose whether or not the container can read information from the
device's /sys folder. The default is False.
2. (Optional) Configure the local volumes that the containerized Lambda function can access.
When you define a volume, the AWS IoT Greengrass Core software mounts the source files to the
destination inside the container.
a. Under Volumes, choose Add volume.
b. For each volume that you add, specify the following options:
529
AWS IoT Greengrass Developer Guide, Version 2
Step 6: Create the Lambda function component
• Physical volume – The path to the source folder on the core device.
• Logical volume – The path to the destination folder in the container.
• Permission – (Optional) The permission to access the source folder from the container.
Choose from the following options:
• Read-only – The Lambda function has read-only access to the source folder. This is the
default selection.
• Read-write – The Lambda function has read/write access to the source folder.
• Add group owner – (Optional) Whether or not to add the system group that runs the Lambda
function component as an owner of the source folder. The default is False.
c. To remove a volume, choose Remove next to the volume that you want to remove.
3. (Optional) Configure the local system devices that the containerized Lambda function can access.
a. Under Devices, choose Add device.
b. For each device that you add, specify the following options:
• Mount path – The path to the system device on the core device.
• Permission – (Optional) The permission to access the system device from the container.
Choose from the following options:
• Read-only – The Lambda function has read-only access to the system device. This is the
default selection.
• Read-write – The Lambda function has read/write access to the source folder.
• Add group owner – (Optional) Whether or not to add the system group that runs the Lambda
function component as an owner of the system device. The default is False.
Step 6: Create the Lambda function component
After you configure settings for your Lambda function component, choose Create to finish creating the
new component.
To run the Lambda function on your core device, you can then deploy the new component to your core
devices. For more information, see Deploy AWS IoT Greengrass components to devices (p. 491).
Import a Lambda function as a component (AWS
CLI)
Use the CreateComponentVersion operation to create components from Lambda functions. When you
call this operation, specify lambdaFunction to import a Lambda function.
Tasks
• Step 1: Define the Lambda function configuration (p. 530)
• Step 2: Create the Lambda function component (p. 543)
Step 1: Define the Lambda function configuration
1. Create a file called lambda-function-component.json, and then copy the following JSON
object into the file. Replace the lambdaArn with the ARN of the Lambda function to import.
530
AWS IoT Greengrass Developer Guide, Version 2
Step 1: Define the Lambda function configuration
"lambdaFunction": {
"lambdaArn": "arn:aws:lambda:region:account-id:function:HelloWorld:1"
}
}
Important
You must specify an ARN that includes the version of the function to import. You can't use
version aliases like $LATEST.
2. (Optional) Specify the name (componentName) of the component. If you omit this parameter, AWS
IoT Greengrass creates the component with the name of the Lambda function.
{
"lambdaFunction": {
"lambdaArn": "arn:aws:lambda:region:account-id:function:HelloWorld:1",
"componentName": "com.example.HelloWorldLambda"
}
}
3. (Optional) Specify the version (componentVersion) for the component. If you omit this parameter,
AWS IoT Greengrass creates the component with the version of the Lambda function as a valid
semantic version. For example, if your function version is 3, the component version becomes 3.0.0.
Note
Each component version that you upload must be unique. Make sure that you upload the
correct component version, because you can't edit it after you upload it.
AWS IoT Greengrass uses semantic versions for components. Semantic versions follow a
major.minor.patch number system. For example, version 1.0.0 represents the first major
release for a component. For more information, see the semantic version specification.
{
"lambdaFunction": {
"lambdaArn": "arn:aws:lambda:region:account-id:function:HelloWorld:1",
"componentName": "com.example.HelloWorldLambda",
"componentVersion": "1.0.0"
}
}
4. (Optional) Specify the platforms that this Lambda function supports. Each platform contains a map
of attributes that identify a platform. All core devices have attributes for operating system (os)
and architecture (architecture). The AWS IoT Greengrass Core software may add other platform
attributes. You can also specify custom platform attributes when you deploy the Greengrass nucleus
component (p. 181) to a core device. Do the following:
a. Add a list of platforms (componentPlatforms) to the Lambda function in lambda-
function-component.json.
{
"lambdaFunction": {
"lambdaArn": "arn:aws:lambda:region:account-id:function:HelloWorld:1",
"componentName": "com.example.HelloWorldLambda",
"componentVersion": "1.0.0",
"componentPlatforms": [
]
}
}
b. Add each supported platform to the list. Each platform has a friendly name to identify it and a
map of attributes. The following example specifies that this function supports x86 devices that
run Linux.
531
AWS IoT Greengrass Developer Guide, Version 2
Step 1: Define the Lambda function configuration
{
"name": "Linux x86",
"attributes": {
"os": "linux",
"architecture": "x86"
}
}
Your lambda-function-component.json might contain a document similar to the following
example.
{
"lambdaFunction": {
"lambdaArn": "arn:aws:lambda:region:account-id:function:HelloWorld:1",
"componentName": "com.example.HelloWorldLambda",
"componentVersion": "1.0.0",
"componentPlatforms": [
{
"name": "Linux x86",
"attributes": {
"os": "linux",
"architecture": "x86"
}
}
]
}
}
5. (Optional) Specify the component dependencies for your Lambda function. When you deploy the
Lambda function component, the deployment includes these dependencies for your function to run.
Important
To import a Lambda function that you created to run on AWS IoT Greengrass V1, you
must define individual component dependencies for the features that your function uses,
such as subscriptions, secrets, and stream manager. Define these components as hard
dependencies (p. 471) so that your Lambda function component restarts if the dependency
changes state. For more information, see Run V1 Lambda functions (p. 11).
Do the following:
a. Add a map of component dependencies (componentDependencies) to the Lambda function in
lambda-function-component.json.
{
"lambdaFunction": {
"lambdaArn": "arn:aws:lambda:region:account-id:function:HelloWorld:1",
"componentName": "com.example.HelloWorldLambda",
"componentVersion": "1.0.0",
"componentPlatforms": [
{
"name": "Linux x86",
"attributes": {
"os": "linux",
"architecture": "x86"
}
}
],
"componentDependencies": {
}
}
532
AWS IoT Greengrass Developer Guide, Version 2
Step 1: Define the Lambda function configuration
b. Add each component dependency to the map. Specify the component name as the key and
specify an object with the following parameters:
• versionRequirement – The npm-style semantic version constraint that identifies the
compatible versions of the component dependency. You can specify a single version or a
range of versions. For more information about semantic version constraints, see the npm
semver calculator.
• dependencyType – (Optional) The type of the dependency. Choose from the following:
• SOFT – The Lambda function component doesn't restart if the dependency changes state.
• HARD – The Lambda function component restarts if the dependency changes state.
The default is HARD.
The following example specifies that this Lambda function depends on any version in the first
major version of the stream manager component (p. 398). The Lambda function component
restarts when stream manager restarts or updates.
{
"aws.greengrass.StreamManager": {
"versionRequirement": "^1.0.0",
"dependencyType": "HARD"
}
}
Your lambda-function-component.json might contain a document similar to the following
example.
{
"lambdaFunction": {
"lambdaArn": "arn:aws:lambda:region:account-id:function:HelloWorld:1",
"componentName": "com.example.HelloWorldLambda",
"componentVersion": "1.0.0",
"componentPlatforms": [
{
"name": "Linux x86",
"attributes": {
"os": "linux",
"architecture": "x86"
}
}
],
"componentDependencies": {
"aws.greengrass.StreamManager": {
"versionRequirement": "^1.0.0",
"dependencyType": "HARD"
}
}
}
}
6. (Optional) Configure the Lambda function parameters to use to run the function. You can configure
options such environment variables, message event sources, timeouts, and container settings. Do the
following:
a. Add the Lambda parameters object (componentLambdaParameters) to the Lambda function
in lambda-function-component.json.
533
AWS IoT Greengrass Developer Guide, Version 2
Step 1: Define the Lambda function configuration
{
"lambdaFunction": {
"lambdaArn": "arn:aws:lambda:region:account-id:function:HelloWorld:1",
"componentName": "com.example.HelloWorldLambda",
"componentVersion": "1.0.0",
"componentPlatforms": [
{
"name": "Linux x86",
"attributes": {
"os": "linux",
"architecture": "x86"
}
}
],
"componentDependencies": {
"aws.greengrass.StreamManager": {
"versionRequirement": "^1.0.0",
"dependencyType": "HARD"
}
},
"componentLambdaParameters": {
}
}
}
b. (Optional) Specify the event sources to which the Lambda function subscribes for work
messages. The Lambda function is called when it receives a message from an event source.
You can subscribe this function to local publish/subscribe messages and AWS IoT Core MQTT
messages. Do the following:
i. Add the list of event sources (eventSources) to the Lambda function parameters.
{
"lambdaFunction": {
"lambdaArn": "arn:aws:lambda:region:account-id:function:HelloWorld:1",
"componentName": "com.example.HelloWorldLambda",
"componentVersion": "1.0.0",
"componentPlatforms": [
{
"name": "Linux x86",
"attributes": {
"os": "linux",
"architecture": "x86"
}
}
],
"componentDependencies": {
"aws.greengrass.StreamManager": {
"versionRequirement": "^1.0.0",
"dependencyType": "HARD"
}
},
"componentLambdaParameters": {
"eventSources": [
]
}
}
}
ii. Add each event source to the list. Each event source has the following parameters:
534
AWS IoT Greengrass Developer Guide, Version 2
Step 1: Define the Lambda function configuration
• topic – The topic to subscribe for messages. This topic supports MQTT topic wildcards (+
and #) when you subscribe to AWS IoT Core MQTT topics.
• type – The type of event source. Choose from the following:
• PUB_SUB – Subscribe to local publish/subscribe messages.
• IOT_CORE – Subscribe to AWS IoT Core MQTT messages.
The following example subscribes to AWS IoT Core MQTT on topics that match the
hello/world/+ topic filter.
{
"topic": "hello/world/+",
"type": "IOT_CORE"
}
Your lambda-function-component.json might look similar to the following
example.
{
"lambdaFunction": {
"lambdaArn": "arn:aws:lambda:region:account-id:function:HelloWorld:1",
"componentName": "com.example.HelloWorldLambda",
"componentVersion": "1.0.0",
"componentPlatforms": [
{
"name": "Linux x86",
"attributes": {
"os": "linux",
"architecture": "x86"
}
}
],
"componentDependencies": {
"aws.greengrass.StreamManager": {
"versionRequirement": "^1.0.0",
"dependencyType": "HARD"
}
},
"componentLambdaParameters": {
"eventSources": [
{
"topic": "hello/world/+",
"type": "IOT_CORE"
}
]
}
}
}
c. (Optional) Specify any of the following parameters in the Lambda function parameters object:
• environmentVariables – The map of environment variables that are available to the
Lambda function when it runs.
• execArgs – The list of arguments to pass to the Lambda function when it runs.
• inputPayloadEncodingType – The type of payload that the Lambda function supports.
Choose from the following options:
• json
• binary
535
AWS IoT Greengrass Developer Guide, Version 2
Step 1: Define the Lambda function configuration
Default: json
• pinned – Whether or not the Lambda function is pinned. The default is true.
• A pinned (or long-lived) Lambda function starts when AWS IoT Greengrass starts and keeps
running in its own container.
• A non-pinned (or on-demand) Lambda function starts only when it receives a work item
and exits after it remains idle for a specified maximum idle time. If the function has
multiple work items, the AWS IoT Greengrass Core software creates multiple instances of
the function.
Use maxIdleTimeInSeconds to set the maximum idle time for your function.
• timeoutInSeconds – The maximum amount of time in seconds that the Lambda function
can run before it times out. The default is 3 seconds.
• statusTimeoutInSeconds – The interval in seconds at which the Lambda function
component sends status updates to the Lambda manager component. This parameter applies
only to pinned functions. The default is 60 seconds.
• maxIdleTimeInSeconds – The maximum amount of time in seconds that a non-pinned
Lambda function can idle before the AWS IoT Greengrass Core software stops its process. The
default is 60 seconds.
• maxInstancesCount – The maximum number of instances that a non-pinned Lambda
function can run at the same time. The default is 100 instances.
• maxQueueSize – The maximum size of the message queue for the Lambda function
component. The AWS IoT Greengrass Core software stores messages in a FIFO (first-in-first-
out) queue until it can run the Lambda function to consume each message. The default is
1,000 messages.
Your lambda-function-component.json might contain a document similar to the following
example.
{
"lambdaFunction": {
"lambdaArn": "arn:aws:lambda:region:account-id:function:HelloWorld:1",
"componentName": "com.example.HelloWorldLambda",
"componentVersion": "1.0.0",
"componentPlatforms": [
{
"name": "Linux x86",
"attributes": {
"os": "linux",
"architecture": "x86"
}
}
],
"componentDependencies": {
"aws.greengrass.StreamManager": {
"versionRequirement": "^1.0.0",
"dependencyType": "HARD"
}
},
"componentLambdaParameters": {
"eventSources": [
{
"topic": "hello/world/+",
"type": "IOT_CORE"
}
],
"environmentVariables": {
"LIMIT": "300"
536
AWS IoT Greengrass Developer Guide, Version 2
Step 1: Define the Lambda function configuration
},
"execArgs": [
"-d"
],
"inputPayloadEncodingType": "json",
"pinned": true,
"timeoutInSeconds": 120,
"statusTimeoutInSeconds": 30,
"maxIdleTimeInSeconds": 30,
"maxInstancesCount": 50,
"maxQueueSize": 500
}
}
}
d. (Optional) Configure the container settings for the Lambda function. By default, Lambda
functions run in an isolated runtime environment inside the AWS IoT Greengrass Core software.
You can also choose to run the Lambda function as a process without any isolation. If you run
the Lambda function in a container, you configure the memory size of the container and what
system resources are available to the Lambda function. Do the following:
i. Add the Linux process parameters object (linuxProcessParams) to the Lambda
parameters object in lambda-function-component.json.
{
"lambdaFunction": {
"lambdaArn": "arn:aws:lambda:region:account-id:function:HelloWorld:1",
"componentName": "com.example.HelloWorldLambda",
"componentVersion": "1.0.0",
"componentPlatforms": [
{
"name": "Linux x86",
"attributes": {
"os": "linux",
"architecture": "x86"
}
}
],
"componentDependencies": {
"aws.greengrass.StreamManager": {
"versionRequirement": "^1.0.0",
"dependencyType": "HARD"
}
},
"componentLambdaParameters": {
"eventSources": [
{
"topic": "hello/world/+",
"type": "IOT_CORE"
}
],
"environmentVariables": {
"LIMIT": "300"
},
"execArgs": [
"-d"
],
"inputPayloadEncodingType": "json",
"pinned": true,
"timeoutInSeconds": 120,
"statusTimeoutInSeconds": 30,
"maxIdleTimeInSeconds": 30,
"maxInstancesCount": 50,
"maxQueueSize": 500,
537
AWS IoT Greengrass Developer Guide, Version 2
Step 1: Define the Lambda function configuration
"linuxProcessParams": {
}
}
}
}
ii. (Optional) Specify whether or not the Lambda function runs in a container. Add the
isolationMode parameter to the process parameters object, and choose from the
following options:
• GreengrassContainer – The Lambda function runs in a container.
• NoContainer – The Lambda function runs as a process without any isolation.
The default is GreengrassContainer.
iii. (Optional) If you run the Lambda function in a container, you can configure the amount of
memory and the system resources, such as volumes and devices, to make available to the
container. Do the following:
A. Add the container parameters object (containerParams) to the Linux process
parameters object in lambda-function-component.json.
{
"lambdaFunction": {
"lambdaArn": "arn:aws:lambda:region:account-id:function:HelloWorld:1",
"componentName": "com.example.HelloWorldLambda",
"componentVersion": "1.0.0",
"componentPlatforms": [
{
"name": "Linux x86",
"attributes": {
"os": "linux",
"architecture": "x86"
}
}
],
"componentDependencies": {
"aws.greengrass.StreamManager": {
"versionRequirement": "^1.0.0",
"dependencyType": "HARD"
}
},
"componentLambdaParameters": {
"eventSources": [
{
"topic": "hello/world/+",
"type": "IOT_CORE"
}
],
"environmentVariables": {
"LIMIT": "300"
},
"execArgs": [
"-d"
],
"inputPayloadEncodingType": "json",
"pinned": true,
"timeoutInSeconds": 120,
"statusTimeoutInSeconds": 30,
"maxIdleTimeInSeconds": 30,
"maxInstancesCount": 50,
"maxQueueSize": 500,
538
AWS IoT Greengrass Developer Guide, Version 2
Step 1: Define the Lambda function configuration
"linuxProcessParams": {
"containerParams": {
}
}
}
}
}
B. (Optional) Add the memorySizeInKB parameter to specify the memory size of the
container. The default is 16,384 KB (16 MB).
C. (Optional) Add the mountROSysfs parameter to specify whether or not the container
can read information from the device's /sys folder. The default is false.
D. (Optional) Configure the local volumes that the containerized Lambda function can
access. When you define a volume, the AWS IoT Greengrass Core software mounts the
source files to the destination inside the container. Do the following:
I. Add the list of volumes (volumes) to the container parameters.
{
"lambdaFunction": {
"lambdaArn": "arn:aws:lambda:region:account-
id:function:HelloWorld:1",
"componentName": "com.example.HelloWorldLambda",
"componentVersion": "1.0.0",
"componentPlatforms": [
{
"name": "Linux x86",
"attributes": {
"os": "linux",
"architecture": "x86"
}
}
],
"componentDependencies": {
"aws.greengrass.StreamManager": {
"versionRequirement": "^1.0.0",
"dependencyType": "HARD"
}
},
"componentLambdaParameters": {
"eventSources": [
{
"topic": "hello/world/+",
"type": "IOT_CORE"
}
],
"environmentVariables": {
"LIMIT": "300"
},
"execArgs": [
"-d"
],
"inputPayloadEncodingType": "json",
"pinned": true,
"timeoutInSeconds": 120,
"statusTimeoutInSeconds": 30,
"maxIdleTimeInSeconds": 30,
"maxInstancesCount": 50,
"maxQueueSize": 500,
"linuxProcessParams": {
"containerParams": {
"memorySizeInKB": 32768,
539
AWS IoT Greengrass Developer Guide, Version 2
Step 1: Define the Lambda function configuration
"mountROSysfs": true,
"volumes": [
]
}
}
}
}
}
II. Add each volume to the list. Each volume has the following parameters:
• sourcePath – The path to the source folder on the core device.
• destinationPath – The path to the destination folder in the container.
• permission – (Optional) The permission to access the source folder from the
container. Choose from the following options:
• ro – The Lambda function has read-only access to the source folder.
• rw – The Lambda function has read-write access to the source folder.
The default is ro.
• addGroupOwner – (Optional) Whether or not to add the system group that runs
the Lambda function component as an owner of the source folder. The default is
false.
Your lambda-function-component.json might contain a document similar to
the following example.
{
"lambdaFunction": {
"lambdaArn": "arn:aws:lambda:region:account-
id:function:HelloWorld:1",
"componentName": "com.example.HelloWorldLambda",
"componentVersion": "1.0.0",
"componentPlatforms": [
{
"name": "Linux x86",
"attributes": {
"os": "linux",
"architecture": "x86"
}
}
],
"componentDependencies": {
"aws.greengrass.StreamManager": {
"versionRequirement": "^1.0.0",
"dependencyType": "HARD"
}
},
"componentLambdaParameters": {
"eventSources": [
{
"topic": "hello/world/+",
"type": "IOT_CORE"
}
],
"environmentVariables": {
"LIMIT": "300"
},
"execArgs": [
"-d"
],
540
AWS IoT Greengrass Developer Guide, Version 2
Step 1: Define the Lambda function configuration
"inputPayloadEncodingType": "json",
"pinned": true,
"timeoutInSeconds": 120,
"statusTimeoutInSeconds": 30,
"maxIdleTimeInSeconds": 30,
"maxInstancesCount": 50,
"maxQueueSize": 500,
"linuxProcessParams": {
"containerParams": {
"memorySizeInKB": 32768,
"mountROSysfs": true,
"volumes": [
{
"sourcePath": "/var/data/src",
"destinationPath": "/var/data/dest",
"permission": "rw",
"addGroupOwner": true
}
]
}
}
}
}
}
E. (Optional) Configure the local system devices that the containerized Lambda function
can access. Do the following:
I. Add the list of system devices (devices) to the container parameters.
{
"lambdaFunction": {
"lambdaArn": "arn:aws:lambda:region:account-
id:function:HelloWorld:1",
"componentName": "com.example.HelloWorldLambda",
"componentVersion": "1.0.0",
"componentPlatforms": [
{
"name": "Linux x86",
"attributes": {
"os": "linux",
"architecture": "x86"
}
}
],
"componentDependencies": {
"aws.greengrass.StreamManager": {
"versionRequirement": "^1.0.0",
"dependencyType": "HARD"
}
},
"componentLambdaParameters": {
"eventSources": [
{
"topic": "hello/world/+",
"type": "IOT_CORE"
}
],
"environmentVariables": {
"LIMIT": "300"
},
"execArgs": [
"-d"
],
"inputPayloadEncodingType": "json",
541
AWS IoT Greengrass Developer Guide, Version 2
Step 1: Define the Lambda function configuration
"pinned": true,
"timeoutInSeconds": 120,
"statusTimeoutInSeconds": 30,
"maxIdleTimeInSeconds": 30,
"maxInstancesCount": 50,
"maxQueueSize": 500,
"linuxProcessParams": {
"containerParams": {
"memorySizeInKB": 32768,
"mountROSysfs": true,
"volumes": [
{
"sourcePath": "/var/data/src",
"destinationPath": "/var/data/dest",
"permission": "rw",
"addGroupOwner": true
}
],
"devices": [
]
}
}
}
}
}
II. Add each system device to the list. Each system device has the following
parameters:
• path – The path to the system device on the core device.
• permission – (Optional) The permission to access the system device from the
container. Choose from the following options:
• ro – The Lambda function has read-only access to the system device.
• rw – The Lambda function has read-write access to the system device.
The default is ro.
• addGroupOwner – (Optional) Whether or not to add the system group that runs
the Lambda function component as an owner of the system device. The default
is false.
Your lambda-function-component.json might contain a document similar to the
following example.
{
"lambdaFunction": {
"lambdaArn": "arn:aws:lambda:region:account-id:function:HelloWorld:1",
"componentName": "com.example.HelloWorldLambda",
"componentVersion": "1.0.0",
"componentPlatforms": [
{
"name": "Linux x86",
"attributes": {
"os": "linux",
"architecture": "x86"
}
}
],
"componentDependencies": {
"aws.greengrass.StreamManager": {
"versionRequirement": "^1.0.0",
542
AWS IoT Greengrass Developer Guide, Version 2
Step 2: Create the Lambda function component
"dependencyType": "HARD"
}
},
"componentLambdaParameters": {
"eventSources": [
{
"topic": "hello/world/+",
"type": "IOT_CORE"
}
],
"environmentVariables": {
"LIMIT": "300"
},
"execArgs": [
"-d"
],
"inputPayloadEncodingType": "json",
"pinned": true,
"timeoutInSeconds": 120,
"statusTimeoutInSeconds": 30,
"maxIdleTimeInSeconds": 30,
"maxInstancesCount": 50,
"maxQueueSize": 500,
"linuxProcessParams": {
"containerParams": {
"memorySizeInKB": 32768,
"mountROSysfs": true,
"volumes": [
{
"sourcePath": "/var/data/src",
"destinationPath": "/var/data/dest",
"permission": "rw",
"addGroupOwner": true
}
],
"devices": [
{
"path": "/dev/sda3",
"permission": "rw",
"addGroupOwner": true
}
]
}
}
}
}
}
7. (Optional) Add tags (tags) for the component. For more information, see Tag your AWS IoT
Greengrass Version 2 resources (p. 919).
Step 2: Create the Lambda function component
1. Run the following command to create the Lambda function component from lambda-function-
component.json.
aws greengrassv2 create-component-version --cli-input-json file://lambda-function-
component.json
The response looks similar to the following example if the request succeeds.
543
AWS IoT Greengrass Developer Guide, Version 2
Step 2: Create the Lambda function component
{
"arn":
"arn:aws:greengrass:region:123456789012:components:com.example.HelloWorldLambda:versions:1.0.0",
"componentName": "com.example.HelloWorldLambda",
"componentVersion": "1.0.0",
"creationTimestamp": "Mon Dec 15 20:56:34 UTC 2020",
"status": {
"componentState": "REQUESTED",
"message": "NONE",
"errors": {}
}
}
Copy the arn from the output to check the state of the component in the next step.
2. When you create a component, its state is REQUESTED. Then, AWS IoT Greengrass validates that the
component is deployable. You can run the following command to query the component status and
verify that your component is deployable. Replace the arn with the ARN from the previous step.
aws greengrassv2 describe-component \
--arn "arn:aws:greengrass:region:account-
id:components:com.example.HelloWorldLambda:versions:1.0.0"
If the component validates, the response indicates that the component state is DEPLOYABLE.
{
"arn": "arn:aws:greengrass:region:account-
id:components:com.example.HelloWorldLambda:versions:1.0.0",
"componentName": "com.example.HelloWorldLambda",
"componentVersion": "1.0.0",
"creationTimestamp": "2020-12-15T20:56:34.376000-08:00",
"publisher": "AWS Lambda",
"status": {
"componentState": "DEPLOYABLE",
"message": "NONE",
"errors": {}
},
"platforms": [
{
"name": "Linux x86",
"attributes": {
"architecture": "x86",
"os": "linux"
}
}
]
}
After the component is DEPLOYABLE, you can deploy the Lambda function to your core devices. For
more information, see Deploy AWS IoT Greengrass components to devices (p. 491).
544
AWS IoT Greengrass Developer Guide, Version 2
Supported SDKs
Use the AWS IoT Device SDK to
communicate with the Greengrass
nucleus, other components, and
AWS IoT Core
Components running on your core device can use the AWS IoT Greengrass Core interprocess
communication (IPC) library in the AWS IoT Device SDK to communicate with the AWS IoT Greengrass
nucleus and other Greengrass components. To develop and run custom components that use IPC, you
must use the AWS IoT Device SDK to connect to the AWS IoT Greengrass Core IPC service and perform
IPC operations.
The IPC interface supports two types of operations:
• Request/response
Components send a request to the IPC service and receive a response that contains the result of the
request.
• Subscription
Components send a subscription request to the IPC service and expect a stream of event messages in
response. Components provide a subscription handler that handles event messages, errors, and stream
closure. The AWS IoT Device SDK includes a handler interface with the correct response and event
types for each IPC operation. For more information, see Subscribe to IPC event streams (p. 554).
Topics
• Supported SDKs for interprocess communication (p. 545)
• Connect to the AWS IoT Greengrass Core IPC service (p. 546)
• Authorize components to perform IPC operations (p. 552)
• Subscribe to IPC event streams (p. 554)
• Publish/subscribe local messages (p. 561)
• Publish/subscribe AWS IoT Core MQTT messages (p. 586)
• Interact with component lifecycle (p. 601)
• Interact with component configuration (p. 606)
• Retrieve secret values (p. 610)
• Interact with local shadows (p. 618)
Supported SDKs for interprocess communication
The AWS IoT Greengrass Core IPC libraries are included in the following AWS IoT Device SDK versions.
• AWS IoT Device SDK for Java v2 (v1.2.10 or later)
For more information about using the AWS IoT Device SDK for Java v2 to connect to the AWS IoT
Greengrass Core IPC service, see Use AWS IoT Device SDK for Java v2 (p. 546).
• AWS IoT Device SDK for Python v2 (v1.5.3 or later)
545
AWS IoT Greengrass Developer Guide, Version 2
Connect to the AWS IoT Greengrass Core IPC service
For more information about using the AWS IoT Device SDK for Python v2 to connect to the AWS IoT
Greengrass Core IPC service, see Use AWS IoT Device SDK for Python v2 (p. 548).
• AWS IoT Device SDK for C++ v2 (Linux: v1.13.0 or later; Windows: v1.14.6 or later)
For more information about using the AWS IoT Device SDK for C++ v2 to connect to the AWS IoT
Greengrass Core IPC service, see Use AWS IoT Device SDK for C++ v2 (p. 549).
Connect to the AWS IoT Greengrass Core IPC
service
To use interprocess communication in your custom component, you must create a connection to an
IPC server socket that the AWS IoT Greengrass Core software runs. Complete the following tasks to
download and use the AWS IoT Device SDK in the language of your choice.
Use AWS IoT Device SDK for Java v2
To use the AWS IoT Device SDK for Java v2
1. Download the AWS IoT Device SDK for Java v2 (v1.2.10 or later).
2. Do one of the following to run your custom code in your component:
• Build your component as a JAR file that includes the AWS IoT Device SDK, and run this JAR file in
your component recipe.
• Define the AWS IoT Device SDK JAR as a component artifact, and add that artifact to the classpath
when you run your application in your component recipe.
3. Create a connection to the AWS IoT Greengrass Core IPC service. The IPC client,
GreengrassCoreIPCClient, requires an EventStreamRPCConnection. Download the following
IPCUtils class that provides this connection for you.
/* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: Apache-2.0 */
package com.example.greengrass.util;
import software.amazon.awssdk.crt.io.ClientBootstrap;
import software.amazon.awssdk.crt.io.EventLoopGroup;
import software.amazon.awssdk.crt.io.SocketOptions;
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnectionConfig;
import software.amazon.awssdk.eventstreamrpc.GreengrassConnectMessageSupplier;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
public final class IPCUtils {
// Port number is not used in domain sockets.
// It is ignored but the field needs to be set when creating socket connection.
public static final int DEFAULT_PORT_NUMBER = 8033;
private static EventStreamRPCConnection clientConnection = null;
private IPCUtils() {
public static EventStreamRPCConnection getEventStreamRpcConnection()
throws ExecutionException, InterruptedException {
546
AWS IoT Greengrass Developer Guide, Version 2
Connect to the AWS IoT Greengrass Core IPC service
String ipcServerSocketPath =
System.getenv("AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT");
String authToken = System.getenv("SVCUID");
SocketOptions socketOptions = IPCUtils.getSocketOptionsForIPC();
if (clientConnection == null) {
clientConnection = connectToGGCOverEventStreamIPC(socketOptions, authToken,
ipcServerSocketPath);
}
return clientConnection;
}
private static EventStreamRPCConnection
connectToGGCOverEventStreamIPC(SocketOptions socketOptions,
String
authToken, String ipcServerSocketPath)
throws ExecutionException, InterruptedException {
try (EventLoopGroup elGroup = new EventLoopGroup(1);
ClientBootstrap clientBootstrap = new ClientBootstrap(elGroup, null)) {
final EventStreamRPCConnectionConfig config =
new EventStreamRPCConnectionConfig(clientBootstrap, elGroup,
socketOptions, null,
ipcServerSocketPath, DEFAULT_PORT_NUMBER,
GreengrassConnectMessageSupplier.connectMessageSupplier(authToken));
final CompletableFuture<Void> connected = new CompletableFuture<>();
final EventStreamRPCConnection connection = new
EventStreamRPCConnection(config);
final boolean[] disconnected = {false};
final int[] disconnectedCode = {-1};
connection.connect(new EventStreamRPCConnection.LifecycleHandler() {
// Only called on successful connection.
@Override
public void onConnect() {
connected.complete(null);
}
@Override
public void onDisconnect(int errorCode) {
disconnected[0] = true;
disconnectedCode[0] = errorCode;
clientConnection = null;
}
// This on error is for any error that is connection level, including
problems during connect()
@Override
public boolean onError(Throwable t) {
connected.completeExceptionally(t);
clientConnection = null;
return true; // True instructs handler to disconnect due to this
error.
}
});
connected.get();
return connection;
}
}
private static SocketOptions getSocketOptionsForIPC() {
SocketOptions socketOptions = new SocketOptions();
socketOptions.connectTimeoutMs = 3000;
socketOptions.domain = SocketOptions.SocketDomain.LOCAL;
547
AWS IoT Greengrass Developer Guide, Version 2
Connect to the AWS IoT Greengrass Core IPC service
socketOptions.type = SocketOptions.SocketType.STREAM;
return socketOptions;
}
}
4. Use the following code to create the IPC client.
try (EventStreamRPCConnection eventStreamRPCConnection =
IPCUtils.getEventStreamRpcConnection()) {
GreengrassCoreIPCClient ipcClient = new
GreengrassCoreIPCClient(eventStreamRPCConnection);
} catch (Exception e) {
LOGGER.log(Level.SEVERE, "Exception occurred when using IPC.", e);
System.exit(1);
}
Use AWS IoT Device SDK for Python v2
To use the AWS IoT Device SDK for Python v2
1. Download the AWS IoT Device SDK for Python (v1.5.3 or later).
2. Add the SDK's installation steps to the install lifecycle in your component's recipe.
3. Create a connection to the AWS IoT Greengrass Core IPC service. Complete the following steps to
create the IPC client and establish a connection.
SDK v1.5.4 or later
Use the following code to create the IPC client.
import awsiot.greengrasscoreipc
ipc_client = awsiot.greengrasscoreipc.connect()
SDK v1.5.3
1. Download the following IPCUtils class that provides the IPC server connection for you.
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
import os
from awscrt.io import (
ClientBootstrap,
DefaultHostResolver,
EventLoopGroup,
SocketDomain,
SocketOptions,
)
from awsiot.eventstreamrpc import Connection, LifecycleHandler,
MessageAmendment
TIMEOUT = 10
class IPCUtils:
def connect(self):
elg = EventLoopGroup()
resolver = DefaultHostResolver(elg)
548
AWS IoT Greengrass Developer Guide, Version 2
Connect to the AWS IoT Greengrass Core IPC service
bootstrap = ClientBootstrap(elg, resolver)
socket_options = SocketOptions()
socket_options.domain = SocketDomain.Local
amender =
MessageAmendment.create_static_authtoken_amender(os.getenv("SVCUID"))
hostname =
os.getenv("AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT")
connection = Connection(
host_name=hostname,
port=8033,
bootstrap=bootstrap,
socket_options=socket_options,
connect_message_amender=amender,
)
self.lifecycle_handler = LifecycleHandler()
connect_future = connection.connect(self.lifecycle_handler)
connect_future.result(TIMEOUT)
return connection
2. Use the following code to create the IPC client.
import awsiot.greengrasscoreipc.client as client
ipc_utils = IPCUtils()
connection = ipc_utils.connect()
ipc_client = client.GreengrassCoreIPCClient(connection)
Use AWS IoT Device SDK for C++ v2
Note
AWS IoT Greengrass doesn't currently support this feature on Windows core devices.
To build the AWS IoT Device SDK v2 for C++, a device must have the following tools:
• C++ 11 or later
• CMake 3.1 or later
• One of the following compilers:
• GCC 4.8 or later
• Clang 3.9 or later
• MSVC 2015 or later
To use the AWS IoT Device SDK for C++ v2
1. Download the AWS IoT Device SDK for C++ v2 (Linux: v1.13.0 or later; Windows: v1.14.6 or later).
2. Follow the installation instructions in the README to build the AWS IoT Device SDK for C++ v2 from
source.
3. In your C++ build tool, link the Greengrass IPC library, AWS::GreengrassIpc-cpp, that you built
in the previous step. The following CMakeLists.txt example links the Greengrass IPC library to a
project that you build with CMake.
cmake_minimum_required(VERSION 3.1)
project (greengrassv2_pubsub_subscriber)
file(GLOB MAIN_SRC
"*.h"
"*.cpp"
)
549
AWS IoT Greengrass Developer Guide, Version 2
Connect to the AWS IoT Greengrass Core IPC service
add_executable(${PROJECT_NAME} ${MAIN_SRC})
set_target_properties(${PROJECT_NAME} PROPERTIES
LINKER_LANGUAGE CXX
CXX_STANDARD 11)
find_package(aws-crt-cpp PATHS ~/sdk-cpp-workspace/build)
find_package(EventstreamRpc-cpp PATHS ~/sdk-cpp-workspace/build)
find_package(GreengrassIpc-cpp PATHS ~/sdk-cpp-workspace/build)
target_link_libraries(${PROJECT_NAME} AWS::GreengrassIpc-cpp)
4. In your component code, create a connection to the AWS IoT Greengrass Core IPC service to create
an IPC client (Aws::Greengrass::GreengrassCoreIpcClient). You must define an IPC
connection lifecycle handler that handles IPC connection, disconnection, and error events. The
following example creates an IPC client and an IPC connection lifecycle handler that prints when the
IPC client connects, disconnects, and encounters errors.
#include <iostream>
#include <aws/crt/Api.h>
#include <aws/greengrass/GreengrassCoreIpcClient.h>
using namespace Aws::Crt;
using namespace Aws::Greengrass;
class IpcClientLifecycleHandler : public ConnectionLifecycleHandler {
void OnConnectCallback() override {
std::cout << "OnConnectCallback" << std::endl;
}
void OnDisconnectCallback(RpcError error) override {
std::cout << "OnDisconnectCallback: " << error.StatusToString() << std::endl;
exit(-1);
}
bool OnErrorCallback(RpcError error) override {
std::cout << "OnErrorCallback: " << error.StatusToString() << std::endl;
return true;
}
};
int main() {
// Create the IPC client.
ApiHandle apiHandle(g_allocator);
Io::EventLoopGroup eventLoopGroup(1);
Io::DefaultHostResolver socketResolver(eventLoopGroup, 64, 30);
Io::ClientBootstrap bootstrap(eventLoopGroup, socketResolver);
IpcClientLifecycleHandler ipcLifecycleHandler;
GreengrassCoreIpcClient ipcClient(bootstrap);
auto connectionStatus = ipcClient.Connect(ipcLifecycleHandler).get();
if (!connectionStatus) {
std::cerr << "Failed to establish IPC connection: " <<
connectionStatus.StatusToString() << std::endl;
exit(-1);
}
// Use the IPC client to create an operation request.
// Activate the operation request.
auto activate = operation.Activate(request, nullptr);
activate.wait();
// Wait for Greengrass Core to respond to the request.
auto responseFuture = operation.GetResult();
550
AWS IoT Greengrass Developer Guide, Version 2
Connect to the AWS IoT Greengrass Core IPC service
if (responseFuture.wait_for(std::chrono::seconds(timeout)) ==
std::future_status::timeout) {
std::cerr << "Operation timed out while waiting for response from Greengrass
Core." << std::endl;
exit(-1);
}
// Check the result of the request.
auto response = responseFuture.get();
if (response) {
std::cout << "Successfully published to topic: " << topic << std::endl;
} else {
// An error occurred.
std::cout << "Failed to publish to topic: " << topic << std::endl;
auto errorType = response.GetResultType();
if (errorType == OPERATION_ERROR) {
auto *error = response.GetOperationError();
std::cout << "Operation error: " << error->GetMessage().value() <<
std::endl;
} else {
std::cout << "RPC error: " << response.GetRpcError() << std::endl;
}
exit(-1);
}
return 0;
}
5. To run your custom code in your component, build your code as a binary artifact, and run the binary
artifact in your component recipe. Set the artifact's Execute permission to OWNER to enable the
AWS IoT Greengrass Core software to run the binary artifact.
Your component recipe's Manifests section might look similar to the following example.
JSON
{
...
"Manifests": [
{
"Lifecycle": {
"Run": "{artifacts:path}/greengrassv2_pubsub_subscriber"
},
"Artifacts": [
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.PubSubSubscriberCpp/1.0.0/greengrassv2_pubsub_subscriber",
"Permission": {
"Execute": "OWNER"
}
}
]
}
]
}
YAML
...
Manifests:
- Lifecycle:
Run: {artifacts:path}/greengrassv2_pubsub_subscriber
Artifacts:
551
AWS IoT Greengrass Developer Guide, Version 2
Authorize components to perform IPC operations
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.PubSubSubscriberCpp/1.0.0/greengrassv2_pubsub_subscriber
Permission:
Execute: OWNER
Authorize components to perform IPC operations
To allow your custom components to use some IPC operations, you must define authorization policies
that allow the component to perform the operation on certain resources. Each authorization policy
defines a list of operations and a list of resources that the policy allows. For example, the publish/
subscribe messaging IPC service defines publish and subscribe operations for topic resources. You can
use the * wildcard to allow access to all operations or all resources.
You define authorization policies in the component recipe with the accessControl configuration
parameter. The accessControl object maps IPC service identifiers to lists of authorization policies. You
can define multiple authorization policies for each IPC service to control access. Each authorization policy
has a policy ID, which must be unique among all components.
Tip
To create unique policy IDs, you can combine the component name, IPC service name, and a
counter. For example, a component named com.example.HelloWorld might define two
publish/subscribe authorization policies with the following IDs:
• com.example.HelloWorld:pubsub:1
• com.example.HelloWorld:pubsub:2
Authorization policies use the following format. This object is the accessControl configuration
parameter.
JSON
{
"IPC service identifier": {
"policyId": {
"policyDescription": "description",
"operations": [
"operation1",
"operation2"
],
"resources": [
"resource1",
"resource2"
]
}
}
}
YAML
IPC service identifier:
policyId:
policyDescription: description
operations:
- operation1
- operation2
resources:
- resource1
552
AWS IoT Greengrass Developer Guide, Version 2
Authorize components to perform IPC operations
- resource2
Example Example component recipe with an authorization policy
The following example component recipe includes an accessControl object defines an authorization
policy. This policy authorizes the com.example.HelloWorld component to publish to the test/topic
topic.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.HelloWorld",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that publishes messages.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"accessControl": {
"aws.greengrass.ipc.pubsub": {
"com.example.HelloWorld:pubsub:1": {
"policyDescription": "Allows access to publish to test/topic.",
"operations": [
"aws.greengrass#PublishToTopic"
],
"resources": [
"test/topic"
]
}
}
}
}
},
"Manifests": [
{
"Lifecycle": {
"Run": "java -jar {artifacts:path}/HelloWorld.jar"
}
}
]
}
YAML
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.HelloWorld
ComponentVersion: '1.0.0'
ComponentDescription: A component that publishes messages.
ComponentPublisher: Amazon
ComponentConfiguration:
DefaultConfiguration:
accessControl:
aws.greengrass.ipc.pubsub:
"com.example.HelloWorld:pubsub:1":
policyDescription: Allows access to publish to test/topic.
operations:
- "aws.greengrass#PublishToTopic"
resources:
- "test/topic"
Manifests:
- Lifecycle:
553
AWS IoT Greengrass Developer Guide, Version 2
Subscribe to IPC event streams
Run: |-
java -jar {artifacts:path}/HelloWorld.jar
Subscribe to IPC event streams
You can use IPC operations to subscribe to streams of events on a Greengrass core device. To use a
subscribe operation, define a subscription handler and create a request to the IPC service. Then, the IPC
client runs the subscription handler's functions each time that the core device streams an event message
to your component.
You can close a subscription to stop processing event messages. To do so, call closeStream() (Java),
close() (Python), or Close() (C++) on the subscription operation object that you used to open the
subscription.
The AWS IoT Greengrass Core IPC service supports the following subscribe operations:
• SubscribeToTopic (p. 565)
• SubscribeToIoTCore (p. 590)
• SubscribeToComponentUpdates (p. 603)
• SubscribeToConfigurationUpdate (p. 608)
• SubscribeToValidateConfigurationUpdates (p. 609)
Topics
• Define subscription handlers (p. 554)
• Best practices for subscription handlers (p. 555)
• Example subscription handlers (p. 556)
Define subscription handlers
To define a subscription handler, create a class with callback functions that handle event messages,
errors, and stream closure.
Java
Implement the generic
software.amazon.awssdk.eventstreamrpc.StreamResponseHandler<StreamEventType>
interface. StreamEventType is the type of event message for the subscription operation. Define
the following functions to handle event messages, errors, and stream closure.
void onStreamEvent(StreamEventType event)
The callback that the IPC client calls when it receives an event message, such as an MQTT
message or a component update notification.
boolean onStreamError(Throwable error)
The callback that the IPC client calls when a stream error occurs.
Return true to close the subscription stream as a result of the error, or return false to keep the
stream open.
void onStreamClosed()
The callback that the IPC client calls when the stream closes.
554
AWS IoT Greengrass Developer Guide, Version 2
Best practices for subscription handlers
Python
Extend the stream response handler class that corresponds to the subscription operation. The
AWS IoT Device SDK includes a subscription handler class for each subscription operation.
StreamEventType is the type of event message for the subscription operation. Define the
following functions to handle event messages, errors, and stream closure.
def on_stream_event(self, event: StreamEventType) -> None
The callback that the IPC client calls when it receives an event message, such as an MQTT
message or a component update notification.
def on_stream_error(self, error: Exception) -> bool
The callback that the IPC client calls when a stream error occurs.
Return true to close the subscription stream as a result of the error, or return false to keep the
stream open.
def on_stream_closed(self) -> None
The callback that the IPC client calls when the stream closes.
C++
Implement a class that derives from the stream response handler class that corresponds to the
subscription operation. The AWS IoT Device SDK includes a subscription handler base class for
each subscription operation. StreamEventType is the type of event message for the subscription
operation. Define the following functions to handle event messages, errors, and stream closure.
void OnStreamEvent(StreamEventType *event)
The callback that the IPC client calls when it receives an event message, such as an MQTT
message or a component update notification.
bool OnStreamError(OperationError *error)
The callback that the IPC client calls when a stream error occurs.
Return true to close the subscription stream as a result of the error, or return false to keep the
stream open.
void OnStreamClosed()
The callback that the IPC client calls when the stream closes.
Best practices for subscription handlers
The IPC client uses a single thread that communicates with the IPC server and calls your subscription
handler. You must consider this synchronous behavior when you write subscription handler functions.
Follow these guidelines when you write subscription handler functions.
• Run blocking code asynchronously
The IPC client can't send new requests or process new event messages while the thread is blocked.
You can run blocking code in a separate thread that you run from the handler function. Blocking code
includes sleep calls, loops that continuously run, and synchronous I/O requests that take time to
complete.
• Send new IPC requests asynchronously
555
AWS IoT Greengrass Developer Guide, Version 2
Example subscription handlers
The IPC client can't send a new request from within subscription handler functions, because the
request blocks the handler function if you wait for a response. You can send IPC requests in a separate
thread that you run from the handler function.
• Handle exceptions
The IPC client doesn't handle uncaught exceptions in subscription handler functions. If your handler
function throws an exception, the subscription closes, and the exception doesn't appear in your
component logs. You can catch exceptions in your handler functions to keep the subscription open and
log errors that occur in your code.
Example subscription handlers
The following example demonstrates how to use the SubscribeToTopic (p. 565) operation and a
subscription handler to subscribe to local publish/subscribe messages.
Java
Example Example: Subscribe to local publish/subscribe messages
Note
This example uses an IPCUtils class to create a connection to the AWS IoT Greengrass
Core IPC service. For more information, see Connect to the AWS IoT Greengrass Core IPC
service (p. 546).
package com.aws.greengrass.docs.samples.ipc;
import com.aws.greengrass.docs.samples.ipc.util.IPCUtils;
import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient;
import software.amazon.awssdk.aws.greengrass.SubscribeToTopicResponseHandler;
import software.amazon.awssdk.aws.greengrass.model.SubscribeToTopicRequest;
import software.amazon.awssdk.aws.greengrass.model.SubscribeToTopicResponse;
import software.amazon.awssdk.aws.greengrass.model.SubscriptionResponseMessage;
import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError;
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
import software.amazon.awssdk.eventstreamrpc.StreamResponseHandler;
import java.nio.charset.StandardCharsets;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
public class SubscribeToTopic {
public static final int TIMEOUT_SECONDS = 10;
public static void main(String[] args) {
String topic = args[0];
try (EventStreamRPCConnection eventStreamRPCConnection =
IPCUtils.getEventStreamRpcConnection()) {
GreengrassCoreIPCClient ipcClient =
new GreengrassCoreIPCClient(eventStreamRPCConnection);
StreamResponseHandler<SubscriptionResponseMessage> streamResponseHandler =
new SubscriptionResponseHandler(topic);
SubscribeToTopicResponseHandler responseHandler =
SubscribeToTopic.subscribeToTopic(ipcClient, topic,
streamResponseHandler);
CompletableFuture<SubscribeToTopicResponse> futureResponse =
responseHandler.getResponse();
try {
556
AWS IoT Greengrass Developer Guide, Version 2
Example subscription handlers
futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS);
System.out.println("Successfully subscribed to topic: " + topic);
} catch (TimeoutException e) {
System.err.println("Timeout occurred while subscribing to topic: " +
topic);
} catch (ExecutionException e) {
if (e.getCause() instanceof UnauthorizedError) {
System.err.println("Unauthorized error while publishing to topic: "
+ topic);
} else {
throw e;
}
}
// Keep the main thread alive, or the process will exit.
try {
while (true) {
Thread.sleep(10000);
}
} catch (InterruptedException e) {
System.out.println("Subscribe interrupted.");
}
// To stop subscribing, close the stream.
responseHandler.closeStream();
} catch (InterruptedException e) {
System.out.println("IPC interrupted.");
} catch (ExecutionException e) {
System.err.println("Exception occurred when using IPC.");
e.printStackTrace();
System.exit(1);
}
}
public static SubscribeToTopicResponseHandler
subscribeToTopic(GreengrassCoreIPCClient greengrassCoreIPCClient, String topic,
StreamResponseHandler<SubscriptionResponseMessage> streamResponseHandler) {
SubscribeToTopicRequest subscribeToTopicRequest = new
SubscribeToTopicRequest();
subscribeToTopicRequest.setTopic(topic);
return greengrassCoreIPCClient.subscribeToTopic(subscribeToTopicRequest,
Optional.of(streamResponseHandler));
}
public static class SubscriptionResponseHandler implements
StreamResponseHandler<SubscriptionResponseMessage> {
private final String topic;
public SubscriptionResponseHandler(String topic) {
this.topic = topic;
}
@Override
public void onStreamEvent(SubscriptionResponseMessage
subscriptionResponseMessage) {
try {
String message =
new
String(subscriptionResponseMessage.getBinaryMessage().getMessage(),
StandardCharsets.UTF_8);
System.out.printf("Received new message on topic %s: %s%n", this.topic,
message);
} catch (Exception e) {
System.err.println("Exception occurred while processing subscription
response " +
557
AWS IoT Greengrass Developer Guide, Version 2
Example subscription handlers
"message.");
e.printStackTrace();
}
}
@Override
public boolean onStreamError(Throwable error) {
System.err.println("Received a stream error.");
error.printStackTrace();
return false; // Return true to close stream, false to keep stream open.
}
@Override
public void onStreamClosed() {
System.out.println("Subscribe to topic stream closed.");
}
}
}
Python
Example Example: Subscribe to local publish/subscribe messages
Note
This example assumes that you are using version 1.5.4 or later of the AWS IoT Device SDK
for Python v2. If you are using version 1.5.3 of the SDK, see Use AWS IoT Device SDK for
Python v2 (p. 548) for information about connecting to the AWS IoT Greengrass Core IPC
service.
import time
import traceback
import awsiot.greengrasscoreipc
import awsiot.greengrasscoreipc.client as client
from awsiot.greengrasscoreipc.model import (
SubscribeToTopicRequest,
SubscriptionResponseMessage
)
TIMEOUT = 10
ipc_client = awsiot.greengrasscoreipc.connect()
class StreamHandler(client.SubscribeToTopicStreamHandler):
def __init__(self):
super().__init__()
def on_stream_event(self, event: SubscriptionResponseMessage) -> None:
try:
message_string = str(event.binary_message.message, "utf-8")
# Handle message.
except:
traceback.print_exc()
def on_stream_error(self, error: Exception) -> bool:
# Handle error.
return True # Return True to close stream, False to keep stream open.
def on_stream_closed(self) -> None:
# Handle close.
pass
topic = "my/topic"
558
AWS IoT Greengrass Developer Guide, Version 2
Example subscription handlers
request = SubscribeToTopicRequest()
request.topic = topic
handler = StreamHandler()
operation = ipc_client.new_subscribe_to_topic(handler)
future = operation.activate(request)
future.result(TIMEOUT)
# Keep the main thread alive, or the process will exit.
while True:
time.sleep(10)
# To stop subscribing, close the operation stream.
operation.close()
C++
Example Example: Subscribe to local publish/subscribe messages
#include <iostream>
#include <aws/crt/Api.h>
#include <aws/greengrass/GreengrassCoreIpcClient.h>
using namespace Aws::Crt;
using namespace Aws::Greengrass;
class SubscribeResponseHandler : public SubscribeToTopicStreamHandler {
void OnStreamEvent(SubscriptionResponseMessage *response) override {
auto jsonMessage = response->GetJsonMessage();
if (jsonMessage.has_value() && jsonMessage.value().GetMessage().has_value()) {
auto messageString =
jsonMessage.value().GetMessage().value().View().WriteReadable();
// Handle JSON message.
} else {
auto binaryMessage = response->GetBinaryMessage();
if (binaryMessage.has_value() &&
binaryMessage.value().GetMessage().has_value()) {
auto messageBytes = binaryMessage.value().GetMessage().value();
std::string messageString(messageBytes.begin(), messageBytes.end());
// Handle binary message.
}
}
}
bool OnStreamError(OperationError *error) override {
// Handle error.
return false; // Return true to close stream, false to keep stream open.
}
void OnStreamClosed() override {
// Handle close.
}
};
class IpcClientLifecycleHandler : public ConnectionLifecycleHandler {
void OnConnectCallback() override {
// Handle connection to IPC service.
}
void OnDisconnectCallback(RpcError error) override {
// Handle disconnection from IPC service.
}
bool OnErrorCallback(RpcError error) override {
// Handle IPC service connection error.
559
AWS IoT Greengrass Developer Guide, Version 2
Example subscription handlers
return true;
}
};
int main() {
ApiHandle apiHandle(g_allocator);
Io::EventLoopGroup eventLoopGroup(1);
Io::DefaultHostResolver socketResolver(eventLoopGroup, 64, 30);
Io::ClientBootstrap bootstrap(eventLoopGroup, socketResolver);
IpcClientLifecycleHandler ipcLifecycleHandler;
GreengrassCoreIpcClient ipcClient(bootstrap);
auto connectionStatus = ipcClient.Connect(ipcLifecycleHandler).get();
if (!connectionStatus) {
std::cerr << "Failed to establish IPC connection: " <<
connectionStatus.StatusToString() << std::endl;
exit(-1);
}
String topic("my/topic");
int timeout = 10;
SubscribeToTopicRequest request;
request.SetTopic(topic);
SubscribeResponseHandler streamHandler;
SubscribeToTopicOperation operation = ipcClient.NewSubscribeToTopic(streamHandler);
auto activate = operation.Activate(request, nullptr);
activate.wait();
auto responseFuture = operation.GetResult();
if (responseFuture.wait_for(std::chrono::seconds(timeout)) ==
std::future_status::timeout) {
std::cerr << "Operation timed out while waiting for response from Greengrass
Core." << std::endl;
exit(-1);
}
if (!response) {
// Handle error.
auto errorType = response.GetResultType();
if (errorType == OPERATION_ERROR) {
auto *error = response.GetOperationError();
// Handle operation error.
} else {
// Handle RPC error.
}
exit(-1);
}
// Keep the main thread alive, or the process will exit.
while (true) {
std::this_thread::sleep_for(std::chrono::seconds(10));
}
operation.Close();
return 0;
}
560
AWS IoT Greengrass Developer Guide, Version 2
Publish/subscribe local messages
Publish/subscribe local messages
Publish/subscribe (pubsub) messaging enables you to send and receive messages to topics. Components
can publish messages to topics to send messages to other components. Then, components that are
subscribed to that topic can act on the messages that they receive.
Note
You can't use this publish/subscribe IPC service to publish or subscribe to AWS IoT Core MQTT.
For more information about how to exchange messages with AWS IoT Core MQTT, see the
Publish/subscribe AWS IoT Core MQTT messages (p. 586).
Topics
• Authorization (p. 561)
• PublishToTopic (p. 562)
• SubscribeToTopic (p. 565)
• Examples (p. 571)
Authorization
To use local publish/subscribe messaging in a custom component, you must define authorization policies
that allows your component to send and receive messages to topics. For information about defining
authorization policies, see Authorize components to perform IPC operations (p. 552).
Authorization policies for publish/subscribe messaging have the following properties.
IPC service identifier: aws.greengrass.ipc.pubsub
Operation Description Resources
Allows a component to publish
aws.greengrass#PublishToTopic A topic string, such as test/
messages to the topics that you topic, or * to allow access to all
specify. topics. This topic string doesn't
support MQTT topic wildcards (#
and +).
Allows a component to subscribe A topic string, such as test/
aws.greengrass#SubscribeToTopic
to messages for the topics that topic, or * to allow access to all
you specify. topics. This topic string doesn't
support MQTT topic wildcards (#
and +).
* Allows a component to publish A topic string, such as test/
and subscribe to messages for topic, or * to allow access to all
the topics that you specify. topics. This topic string doesn't
support MQTT topic wildcards (#
and +).
Example Example authorization policy
The following example authorization policy allows a component to publish and subscribe to all topics.
{
"accessControl": {
"aws.greengrass.ipc.pubsub": {
"com.example.MyLocalPubSubComponent:pubsub:1": {
561
AWS IoT Greengrass Developer Guide, Version 2
PublishToTopic
"policyDescription": "Allows access to publish/subscribe to all topics.",
"operations": [
"aws.greengrass#PublishToTopic",
"aws.greengrass#SubscribeToTopic"
],
"resources": [
"*"
]
}
}
}
}
PublishToTopic
Publish a message to a topic.
Request
This operation's request has the following parameters:
topic
The topic to which to publish the message.
publishMessage (Python: publish_message)
The message to publish. This object, PublishMessage, contains the following information. You
must specify one of jsonMessage and binaryMessage.
jsonMessage (Python: json_message)
(Optional) A JSON message. This object, JsonMessage, contains the following information:
message
The JSON message as an object.
binaryMessage (Python: binary_message)
(Optional) A binary message. This object, BinaryMessage, contains the following information:
message
The binary message as a blob.
This operation doesn't provide any information in its response.
Examples
The following examples demonstrate how to call this operation in custom component code.
Java
Example Example: Publish a binary message
Note
This example uses an IPCUtils class to create a connection to the AWS IoT Greengrass
Core IPC service. For more information, see Connect to the AWS IoT Greengrass Core IPC
service (p. 546).
package com.aws.greengrass.docs.samples.ipc;
562
AWS IoT Greengrass Developer Guide, Version 2
PublishToTopic
import com.aws.greengrass.docs.samples.ipc.util.IPCUtils;
import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient;
import software.amazon.awssdk.aws.greengrass.PublishToTopicResponseHandler;
import software.amazon.awssdk.aws.greengrass.model.*;
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
import java.nio.charset.StandardCharsets;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
public class PublishToTopic {
public static final int TIMEOUT_SECONDS = 10;
public static void main(String[] args) {
String topic = args[0];
String message = args[1];
try (EventStreamRPCConnection eventStreamRPCConnection =
IPCUtils.getEventStreamRpcConnection()) {
GreengrassCoreIPCClient ipcClient =
new GreengrassCoreIPCClient(eventStreamRPCConnection);
PublishToTopicResponseHandler responseHandler =
PublishToTopic.publishBinaryMessageToTopic(ipcClient, topic,
message);
CompletableFuture<PublishToTopicResponse> futureResponse =
responseHandler.getResponse();
try {
futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS);
System.out.println("Successfully published to topic: " + topic);
} catch (TimeoutException e) {
System.err.println("Timeout occurred while publishing to topic: " +
topic);
} catch (ExecutionException e) {
if (e.getCause() instanceof UnauthorizedError) {
System.err.println("Unauthorized error while publishing to topic: "
+ topic);
} else {
throw e;
}
}
} catch (InterruptedException e) {
System.out.println("IPC interrupted.");
} catch (ExecutionException e) {
System.err.println("Exception occurred when using IPC.");
e.printStackTrace();
System.exit(1);
}
}
public static PublishToTopicResponseHandler publishBinaryMessageToTopic(
GreengrassCoreIPCClient greengrassCoreIPCClient, String topic, String
message) {
PublishToTopicRequest publishToTopicRequest = new PublishToTopicRequest();
PublishMessage publishMessage = new PublishMessage();
BinaryMessage binaryMessage = new BinaryMessage();
binaryMessage.setMessage(message.getBytes(StandardCharsets.UTF_8));
publishMessage.setBinaryMessage(binaryMessage);
publishToTopicRequest.setPublishMessage(publishMessage);
publishToTopicRequest.setTopic(topic);
return greengrassCoreIPCClient.publishToTopic(publishToTopicRequest,
Optional.empty());
}
}
563
AWS IoT Greengrass Developer Guide, Version 2
PublishToTopic
Python
Example Example: Publish a binary message
Note
This example assumes that you are using version 1.5.4 or later of the AWS IoT Device SDK
for Python v2. If you are using version 1.5.3 of the SDK, see Use AWS IoT Device SDK for
Python v2 (p. 548) for information about connecting to the AWS IoT Greengrass Core IPC
service.
import awsiot.greengrasscoreipc
from awsiot.greengrasscoreipc.model import (
PublishToTopicRequest,
PublishMessage,
BinaryMessage
)
TIMEOUT = 10
ipc_client = awsiot.greengrasscoreipc.connect()
topic = "my/topic"
message = "Hello, World!"
request = PublishToTopicRequest()
request.topic = topic
publish_message = PublishMessage()
publish_message.binary_message = BinaryMessage()
publish_message.binary_message.message = bytes(message, "utf-8")
request.publish_message = publish_message
operation = ipc_client.new_publish_to_topic()
operation.activate(request)
future = operation.get_response()
future.result(TIMEOUT)
C++
Example Example: Publish a binary message
#include <iostream>
#include <aws/crt/Api.h>
#include <aws/greengrass/GreengrassCoreIpcClient.h>
using namespace Aws::Crt;
using namespace Aws::Greengrass;
class IpcClientLifecycleHandler : public ConnectionLifecycleHandler {
void OnConnectCallback() override {
// Handle connection to IPC service.
}
void OnDisconnectCallback(RpcError error) override {
// Handle disconnection from IPC service.
}
bool OnErrorCallback(RpcError error) override {
// Handle IPC service connection error.
return true;
}
};
int main() {
ApiHandle apiHandle(g_allocator);
564
AWS IoT Greengrass Developer Guide, Version 2
SubscribeToTopic
Io::EventLoopGroup eventLoopGroup(1);
Io::DefaultHostResolver socketResolver(eventLoopGroup, 64, 30);
Io::ClientBootstrap bootstrap(eventLoopGroup, socketResolver);
IpcClientLifecycleHandler ipcLifecycleHandler;
GreengrassCoreIpcClient ipcClient(bootstrap);
auto connectionStatus = ipcClient.Connect(ipcLifecycleHandler).get();
if (!connectionStatus) {
std::cerr << "Failed to establish IPC connection: " <<
connectionStatus.StatusToString() << std::endl;
exit(-1);
}
String topic("my/topic");
String message("Hello, World!");
int timeout = 10;
PublishToTopicRequest request;
Vector<uint8_t> messageData({message.begin(), message.end()});
BinaryMessage binaryMessage;
binaryMessage.SetMessage(messageData);
PublishMessage publishMessage;
publishMessage.SetBinaryMessage(binaryMessage);
request.SetTopic(topic);
request.SetPublishMessage(publishMessage);
PublishToTopicOperation operation = ipcClient.NewPublishToTopic();
auto activate = operation.Activate(request, nullptr);
activate.wait();
auto responseFuture = operation.GetResult();
if (responseFuture.wait_for(std::chrono::seconds(timeout)) ==
std::future_status::timeout) {
std::cerr << "Operation timed out while waiting for response from Greengrass
Core." << std::endl;
exit(-1);
}
if (!response) {
// Handle error.
auto errorType = response.GetResultType();
if (errorType == OPERATION_ERROR) {
auto *error = response.GetOperationError();
// Handle operation error.
} else {
// Handle RPC error.
}
}
return 0;
}
SubscribeToTopic
Subscribe to messages at a topic.
This operation is a subscription operation where you subscribe to a stream of event messages. To use
this operation, define a stream response handler with functions that handle event messages, errors, and
stream closure. For more information, see Subscribe to IPC event streams (p. 554).
Event message type: SubscriptionResponseMessage
Request
This operation's request has the following parameters:
565
AWS IoT Greengrass Developer Guide, Version 2
SubscribeToTopic
topic
The topic to which to subscribe.
Note
This topic doesn't support MQTT topic wildcards (# and +).
Response
This operation's response has the following information:
topicName (Python: topic_name)
The topic to which the message was published.
messages
The stream of messages. This object, SubscriptionResponseMessage, contains the following
information. Each message contains jsonMessage or binaryMessage.
jsonMessage (Python: json_message)
(Optional) A JSON message. This object, JsonMessage, contains the following information:
message
The JSON message as an object.
binaryMessage (Python: binary_message)
(Optional) A binary message. This object, BinaryMessage, contains the following information:
message
The binary message as a blob.
Examples
The following examples demonstrate how to call this operation in custom component code.
Java
Example Example: Subscribe to local publish/subscribe messages
Note
This example uses an IPCUtils class to create a connection to the AWS IoT Greengrass
Core IPC service. For more information, see Connect to the AWS IoT Greengrass Core IPC
service (p. 546).
package com.aws.greengrass.docs.samples.ipc;
import com.aws.greengrass.docs.samples.ipc.util.IPCUtils;
import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient;
import software.amazon.awssdk.aws.greengrass.SubscribeToTopicResponseHandler;
import software.amazon.awssdk.aws.greengrass.model.SubscribeToTopicRequest;
import software.amazon.awssdk.aws.greengrass.model.SubscribeToTopicResponse;
import software.amazon.awssdk.aws.greengrass.model.SubscriptionResponseMessage;
import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError;
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
import software.amazon.awssdk.eventstreamrpc.StreamResponseHandler;
566
AWS IoT Greengrass Developer Guide, Version 2
SubscribeToTopic
import java.nio.charset.StandardCharsets;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
public class SubscribeToTopic {
public static final int TIMEOUT_SECONDS = 10;
public static void main(String[] args) {
String topic = args[0];
try (EventStreamRPCConnection eventStreamRPCConnection =
IPCUtils.getEventStreamRpcConnection()) {
GreengrassCoreIPCClient ipcClient =
new GreengrassCoreIPCClient(eventStreamRPCConnection);
StreamResponseHandler<SubscriptionResponseMessage> streamResponseHandler =
new SubscriptionResponseHandler(topic);
SubscribeToTopicResponseHandler responseHandler =
SubscribeToTopic.subscribeToTopic(ipcClient, topic,
streamResponseHandler);
CompletableFuture<SubscribeToTopicResponse> futureResponse =
responseHandler.getResponse();
try {
futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS);
System.out.println("Successfully subscribed to topic: " + topic);
} catch (TimeoutException e) {
System.err.println("Timeout occurred while subscribing to topic: " +
topic);
} catch (ExecutionException e) {
if (e.getCause() instanceof UnauthorizedError) {
System.err.println("Unauthorized error while publishing to topic: "
+ topic);
} else {
throw e;
}
}
// Keep the main thread alive, or the process will exit.
try {
while (true) {
Thread.sleep(10000);
}
} catch (InterruptedException e) {
System.out.println("Subscribe interrupted.");
}
// To stop subscribing, close the stream.
responseHandler.closeStream();
} catch (InterruptedException e) {
System.out.println("IPC interrupted.");
} catch (ExecutionException e) {
System.err.println("Exception occurred when using IPC.");
e.printStackTrace();
System.exit(1);
}
}
public static SubscribeToTopicResponseHandler
subscribeToTopic(GreengrassCoreIPCClient greengrassCoreIPCClient, String topic,
StreamResponseHandler<SubscriptionResponseMessage> streamResponseHandler) {
SubscribeToTopicRequest subscribeToTopicRequest = new
SubscribeToTopicRequest();
subscribeToTopicRequest.setTopic(topic);
return greengrassCoreIPCClient.subscribeToTopic(subscribeToTopicRequest,
567
AWS IoT Greengrass Developer Guide, Version 2
SubscribeToTopic
Optional.of(streamResponseHandler));
}
public static class SubscriptionResponseHandler implements
StreamResponseHandler<SubscriptionResponseMessage> {
private final String topic;
public SubscriptionResponseHandler(String topic) {
this.topic = topic;
}
@Override
public void onStreamEvent(SubscriptionResponseMessage
subscriptionResponseMessage) {
try {
String message =
new
String(subscriptionResponseMessage.getBinaryMessage().getMessage(),
StandardCharsets.UTF_8);
System.out.printf("Received new message on topic %s: %s%n", this.topic,
message);
} catch (Exception e) {
System.err.println("Exception occurred while processing subscription
response " +
"message.");
e.printStackTrace();
}
}
@Override
public boolean onStreamError(Throwable error) {
System.err.println("Received a stream error.");
error.printStackTrace();
return false; // Return true to close stream, false to keep stream open.
}
@Override
public void onStreamClosed() {
System.out.println("Subscribe to topic stream closed.");
}
}
}
Python
Example Example: Subscribe to local publish/subscribe messages
Note
This example assumes that you are using version 1.5.4 or later of the AWS IoT Device SDK
for Python v2. If you are using version 1.5.3 of the SDK, see Use AWS IoT Device SDK for
Python v2 (p. 548) for information about connecting to the AWS IoT Greengrass Core IPC
service.
import time
import traceback
import awsiot.greengrasscoreipc
import awsiot.greengrasscoreipc.client as client
from awsiot.greengrasscoreipc.model import (
SubscribeToTopicRequest,
SubscriptionResponseMessage
)
568
AWS IoT Greengrass Developer Guide, Version 2
SubscribeToTopic
TIMEOUT = 10
ipc_client = awsiot.greengrasscoreipc.connect()
class StreamHandler(client.SubscribeToTopicStreamHandler):
def __init__(self):
super().__init__()
def on_stream_event(self, event: SubscriptionResponseMessage) -> None:
try:
message_string = str(event.binary_message.message, "utf-8")
# Handle message.
except:
traceback.print_exc()
def on_stream_error(self, error: Exception) -> bool:
# Handle error.
return True # Return True to close stream, False to keep stream open.
def on_stream_closed(self) -> None:
# Handle close.
pass
topic = "my/topic"
request = SubscribeToTopicRequest()
request.topic = topic
handler = StreamHandler()
operation = ipc_client.new_subscribe_to_topic(handler)
future = operation.activate(request)
future.result(TIMEOUT)
# Keep the main thread alive, or the process will exit.
while True:
time.sleep(10)
# To stop subscribing, close the operation stream.
operation.close()
C++
Example Example: Subscribe to local publish/subscribe messages
#include <iostream>
#include <aws/crt/Api.h>
#include <aws/greengrass/GreengrassCoreIpcClient.h>
using namespace Aws::Crt;
using namespace Aws::Greengrass;
class SubscribeResponseHandler : public SubscribeToTopicStreamHandler {
void OnStreamEvent(SubscriptionResponseMessage *response) override {
auto jsonMessage = response->GetJsonMessage();
if (jsonMessage.has_value() && jsonMessage.value().GetMessage().has_value()) {
auto messageString =
jsonMessage.value().GetMessage().value().View().WriteReadable();
// Handle JSON message.
} else {
auto binaryMessage = response->GetBinaryMessage();
if (binaryMessage.has_value() &&
binaryMessage.value().GetMessage().has_value()) {
569
AWS IoT Greengrass Developer Guide, Version 2
SubscribeToTopic
auto messageBytes = binaryMessage.value().GetMessage().value();
std::string messageString(messageBytes.begin(), messageBytes.end());
// Handle binary message.
}
}
}
bool OnStreamError(OperationError *error) override {
// Handle error.
return false; // Return true to close stream, false to keep stream open.
}
void OnStreamClosed() override {
// Handle close.
}
};
class IpcClientLifecycleHandler : public ConnectionLifecycleHandler {
void OnConnectCallback() override {
// Handle connection to IPC service.
}
void OnDisconnectCallback(RpcError error) override {
// Handle disconnection from IPC service.
}
bool OnErrorCallback(RpcError error) override {
// Handle IPC service connection error.
return true;
}
};
int main() {
ApiHandle apiHandle(g_allocator);
Io::EventLoopGroup eventLoopGroup(1);
Io::DefaultHostResolver socketResolver(eventLoopGroup, 64, 30);
Io::ClientBootstrap bootstrap(eventLoopGroup, socketResolver);
IpcClientLifecycleHandler ipcLifecycleHandler;
GreengrassCoreIpcClient ipcClient(bootstrap);
auto connectionStatus = ipcClient.Connect(ipcLifecycleHandler).get();
if (!connectionStatus) {
std::cerr << "Failed to establish IPC connection: " <<
connectionStatus.StatusToString() << std::endl;
exit(-1);
}
String topic("my/topic");
int timeout = 10;
SubscribeToTopicRequest request;
request.SetTopic(topic);
SubscribeResponseHandler streamHandler;
SubscribeToTopicOperation operation = ipcClient.NewSubscribeToTopic(streamHandler);
auto activate = operation.Activate(request, nullptr);
activate.wait();
auto responseFuture = operation.GetResult();
if (responseFuture.wait_for(std::chrono::seconds(timeout)) ==
std::future_status::timeout) {
std::cerr << "Operation timed out while waiting for response from Greengrass
Core." << std::endl;
exit(-1);
}
if (!response) {
570
AWS IoT Greengrass Developer Guide, Version 2
Examples
// Handle error.
auto errorType = response.GetResultType();
if (errorType == OPERATION_ERROR) {
auto *error = response.GetOperationError();
// Handle operation error.
} else {
// Handle RPC error.
}
exit(-1);
}
// Keep the main thread alive, or the process will exit.
while (true) {
std::this_thread::sleep_for(std::chrono::seconds(10));
}
operation.Close();
return 0;
}
Examples
Use the following examples to learn how to use the publish/subscribe IPC service in your components.
Example publish/subscribe publisher (Java)
The following example recipe allows the component to publish to all topics.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.PubSubPublisherJava",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that publishes messages.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"accessControl": {
"aws.greengrass.ipc.pubsub": {
"com.example.PubSubPublisherJava:pubsub:1": {
"policyDescription": "Allows access to publish to all topics.",
"operations": [
"aws.greengrass#PublishToTopic"
],
"resources": [
"*"
]
}
}
}
}
},
"Manifests": [
{
"Lifecycle": {
"Run": "java -jar {artifacts:path}/PubSubPublisher.jar"
}
}
]
}
571
AWS IoT Greengrass Developer Guide, Version 2
Examples
YAML
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.PubSubPublisherJava
ComponentVersion: '1.0.0'
ComponentDescription: A component that publishes messages.
ComponentPublisher: Amazon
ComponentConfiguration:
DefaultConfiguration:
accessControl:
aws.greengrass.ipc.pubsub:
'com.example.PubSubPublisherJava:pubsub:1':
policyDescription: Allows access to publish to all topics.
operations:
- 'aws.greengrass#PublishToTopic'
resources:
- '*'
Manifests:
- Lifecycle:
Run: |-
java -jar {artifacts:path}/PubSubPublisher.jar
The following example Java application demonstrates how to use the publish/subscribe IPC service to
publish messages to other components.
/* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: Apache-2.0 */
package com.example.ipc.pubsub;
import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient;
import software.amazon.awssdk.aws.greengrass.model.*;
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
import java.nio.charset.StandardCharsets;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
public class PubSubPublisher {
public static void main(String[] args) {
String message = "Hello from the pub/sub publisher (Java).";
String topic = "test/topic/java";
try (EventStreamRPCConnection eventStreamRPCConnection =
IPCUtils.getEventStreamRpcConnection()) {
GreengrassCoreIPCClient ipcClient = new
GreengrassCoreIPCClient(eventStreamRPCConnection);
while (true) {
PublishToTopicRequest publishRequest = new PublishToTopicRequest();
PublishMessage publishMessage = new PublishMessage();
BinaryMessage binaryMessage = new BinaryMessage();
binaryMessage.setMessage(message.getBytes(StandardCharsets.UTF_8));
publishMessage.setBinaryMessage(binaryMessage);
publishRequest.setPublishMessage(publishMessage);
publishRequest.setTopic(topic);
CompletableFuture<PublishToTopicResponse> futureResponse = ipcClient
.publishToTopic(publishRequest, Optional.empty()).getResponse();
572
AWS IoT Greengrass Developer Guide, Version 2
Examples
try {
futureResponse.get(10, TimeUnit.SECONDS);
System.out.println("Successfully published to topic: " + topic);
} catch (TimeoutException e) {
System.err.println("Timeout occurred while publishing to topic: " +
topic);
} catch (ExecutionException e) {
if (e.getCause() instanceof UnauthorizedError) {
System.err.println("Unauthorized error while publishing to topic: "
+ topic);
} else {
System.err.println("Execution exception while publishing to topic:
" + topic);
}
throw e;
}
Thread.sleep(5000);
}
} catch (InterruptedException e) {
System.out.println("Publisher interrupted.");
} catch (Exception e) {
System.err.println("Exception occurred when using IPC.");
e.printStackTrace();
System.exit(1);
}
}
}
Example publish/subscribe subscriber (Java)
The following example recipe allows the component to subscribe to all topics.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.PubSubSubscriberJava",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that subscribes to messages.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"accessControl": {
"aws.greengrass.ipc.pubsub": {
"com.example.PubSubSubscriberJava:pubsub:1": {
"policyDescription": "Allows access to subscribe to all topics.",
"operations": [
"aws.greengrass#SubscribeToTopic"
],
"resources": [
"*"
]
}
}
}
}
},
"Manifests": [
{
"Lifecycle": {
"Run": "java -jar {artifacts:path}/PubSubSubscriber.jar"
}
}
573
AWS IoT Greengrass Developer Guide, Version 2
Examples
]
}
YAML
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.PubSubSubscriberJava
ComponentVersion: '1.0.0'
ComponentDescription: A component that subscribes to messages.
ComponentPublisher: Amazon
ComponentConfiguration:
DefaultConfiguration:
accessControl:
aws.greengrass.ipc.pubsub:
'com.example.PubSubSubscriberJava:pubsub:1':
policyDescription: Allows access to subscribe to all topics.
operations:
- 'aws.greengrass#SubscribeToTopic'
resources:
- '*'
Manifests:
- Lifecycle:
Run: |-
java -jar {artifacts:path}/PubSubSubscriber.jar
The following example Java application demonstrates how to use the publish/subscribe IPC service to
subscribe to messages to other components.
/* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: Apache-2.0 */
package com.example.ipc.pubsub;
import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient;
import software.amazon.awssdk.aws.greengrass.SubscribeToTopicResponseHandler;
import software.amazon.awssdk.aws.greengrass.model.SubscribeToTopicRequest;
import software.amazon.awssdk.aws.greengrass.model.SubscribeToTopicResponse;
import software.amazon.awssdk.aws.greengrass.model.SubscriptionResponseMessage;
import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError;
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
import software.amazon.awssdk.eventstreamrpc.StreamResponseHandler;
import java.nio.charset.StandardCharsets;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
public class PubSubSubscriber {
public static void main(String[] args) {
String topic = "test/topic/java";
try (EventStreamRPCConnection eventStreamRPCConnection =
IPCUtils.getEventStreamRpcConnection()) {
GreengrassCoreIPCClient ipcClient = new
GreengrassCoreIPCClient(eventStreamRPCConnection);
SubscribeToTopicRequest subscribeRequest = new SubscribeToTopicRequest();
subscribeRequest.setTopic(topic);
574
AWS IoT Greengrass Developer Guide, Version 2
Examples
SubscribeToTopicResponseHandler operationResponseHandler = ipcClient
.subscribeToTopic(subscribeRequest, Optional.of(new
SubscribeResponseHandler()));
CompletableFuture<SubscribeToTopicResponse> futureResponse =
operationResponseHandler.getResponse();
try {
futureResponse.get(10, TimeUnit.SECONDS);
System.out.println("Successfully subscribed to topic: " + topic);
} catch (TimeoutException e) {
System.err.println("Timeout occurred while subscribing to topic: " +
topic);
throw e;
} catch (ExecutionException e) {
if (e.getCause() instanceof UnauthorizedError) {
System.err.println("Unauthorized error while subscribing to topic: " +
topic);
} else {
System.err.println("Execution exception while subscribing to topic: " +
topic);
}
throw e;
}
// Keep the main thread alive, or the process will exit.
try {
while (true) {
Thread.sleep(10000);
}
} catch (InterruptedException e) {
System.out.println("Subscribe interrupted.");
}
} catch (Exception e) {
System.err.println("Exception occurred when using IPC.");
e.printStackTrace();
System.exit(1);
}
}
private static class SubscribeResponseHandler implements
StreamResponseHandler<SubscriptionResponseMessage> {
@Override
public void onStreamEvent(SubscriptionResponseMessage subscriptionResponseMessage)
{
try {
String message = new String(subscriptionResponseMessage.getBinaryMessage()
.getMessage(), StandardCharsets.UTF_8);
System.out.println("Received new message: " + message);
} catch (Exception e) {
e.printStackTrace();
}
}
@Override
public boolean onStreamError(Throwable error) {
System.err.println("Received a stream error.");
error.printStackTrace();
return false; // Return true to close stream, false to keep stream open.
}
@Override
public void onStreamClosed() {
System.out.println("Subscribe to topic stream closed.");
}
}
575
AWS IoT Greengrass Developer Guide, Version 2
Examples
Example publish/subscribe publisher (Python)
The following example recipe allows the component to publish to all topics.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.PubSubPublisherPython",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that publishes messages.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"accessControl": {
"aws.greengrass.ipc.pubsub": {
"com.example.PubSubPublisherPython:pubsub:1": {
"policyDescription": "Allows access to publish to all topics.",
"operations": [
"aws.greengrass#PublishToTopic"
],
"resources": [
"*"
]
}
}
}
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"Install": "python3 -m pip install --user awsiotsdk",
"Run": "python3 -u {artifacts:path}/pubsub_publisher.py"
}
},
{
"Platform": {
"os": "windows"
},
"Lifecycle": {
"Install": "py -3 -m pip install --user awsiotsdk",
"Run": "py -3 -u {artifacts:path}/pubsub_publisher.py"
}
}
]
}
YAML
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.PubSubPublisherPython
ComponentVersion: 1.0.0
ComponentDescription: A component that publishes messages.
ComponentPublisher: Amazon
ComponentConfiguration:
DefaultConfiguration:
576
AWS IoT Greengrass Developer Guide, Version 2
Examples
accessControl:
aws.greengrass.ipc.pubsub:
com.example.PubSubPublisherPython:pubsub:1:
policyDescription: Allows access to publish to all topics.
operations:
- aws.greengrass#PublishToTopic
resources:
- "*"
Manifests:
- Platform:
os: linux
Lifecycle:
Install: python3 -m pip install --user awsiotsdk
Run: python3 -u {artifacts:path}/pubsub_publisher.py
- Platform:
os: windows
Lifecycle:
Install: py -3 -m pip install --user awsiotsdk
Run: py -3 -u {artifacts:path}/pubsub_publisher.py
The following example Python application demonstrates how to use the publish/subscribe IPC service to
publish messages to other components.
import concurrent.futures
import sys
import time
import traceback
import awsiot.greengrasscoreipc
from awsiot.greengrasscoreipc.model import (
PublishToTopicRequest,
PublishMessage,
BinaryMessage,
UnauthorizedError
)
topic = "test/topic/python"
message = "Hello from the pub/sub publisher (Python)."
TIMEOUT = 10
try:
ipc_client = awsiot.greengrasscoreipc.connect()
while True:
request = PublishToTopicRequest()
request.topic = topic
publish_message = PublishMessage()
publish_message.binary_message = BinaryMessage()
publish_message.binary_message.message = bytes(message, "utf-8")
request.publish_message = publish_message
operation = ipc_client.new_publish_to_topic()
operation.activate(request)
futureResponse = operation.get_response()
try:
futureResponse.result(TIMEOUT)
print('Successfully published to topic: ' + topic)
except concurrent.futures.TimeoutError:
print('Timeout occurred while publishing to topic: ' + topic, file=sys.stderr)
except UnauthorizedError as e:
print('Unauthorized error while publishing to topic: ' + topic,
file=sys.stderr)
577
AWS IoT Greengrass Developer Guide, Version 2
Examples
raise e
except Exception as e:
print('Exception while publishing to topic: ' + topic, file=sys.stderr)
raise e
time.sleep(5)
except InterruptedError:
print('Publisher interrupted.')
except Exception:
print('Exception occurred when using IPC.', file=sys.stderr)
traceback.print_exc()
exit(1)
Example publish/subscribe subscriber (Python)
The following example recipe allows the component to subscribe to all topics.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.PubSubSubscriberPython",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that subscribes to messages.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"accessControl": {
"aws.greengrass.ipc.pubsub": {
"com.example.PubSubSubscriberPython:pubsub:1": {
"policyDescription": "Allows access to subscribe to all topics.",
"operations": [
"aws.greengrass#SubscribeToTopic"
],
"resources": [
"*"
]
}
}
}
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"Install": "python3 -m pip install --user awsiotsdk",
"Run": "python3 -u {artifacts:path}/pubsub_subscriber.py"
}
},
{
"Platform": {
"os": "windows"
},
"Lifecycle": {
"Install": "py -3 -m pip install --user awsiotsdk",
"Run": "py -3 -u {artifacts:path}/pubsub_subscriber.py"
}
}
]
}
578
AWS IoT Greengrass Developer Guide, Version 2
Examples
YAML
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.PubSubSubscriberPython
ComponentVersion: 1.0.0
ComponentDescription: A component that subscribes to messages.
ComponentPublisher: Amazon
ComponentConfiguration:
DefaultConfiguration:
accessControl:
aws.greengrass.ipc.pubsub:
com.example.PubSubSubscriberPython:pubsub:1:
policyDescription: Allows access to subscribe to all topics.
operations:
- aws.greengrass#SubscribeToTopic
resources:
- "*"
Manifests:
- Platform:
os: linux
Lifecycle:
Install: python3 -m pip install --user awsiotsdk
Run: python3 -u {artifacts:path}/pubsub_subscriber.py
- Platform:
os: windows
Lifecycle:
Install: py -3 -m pip install --user awsiotsdk
Run: py -3 -u {artifacts:path}/pubsub_subscriber.py
The following example Python application demonstrates how to use the publish/subscribe IPC service to
subscribe to messages to other components.
import concurrent.futures
import sys
import time
import traceback
import awsiot.greengrasscoreipc
import awsiot.greengrasscoreipc.client as client
from awsiot.greengrasscoreipc.model import (
SubscribeToTopicRequest,
SubscriptionResponseMessage,
UnauthorizedError
)
topic = "test/topic/python"
TIMEOUT = 10
class StreamHandler(client.SubscribeToTopicStreamHandler):
def __init__(self):
super().__init__()
def on_stream_event(self, event: SubscriptionResponseMessage) -> None:
try:
message = str(event.binary_message.message, "utf-8")
print("Received new message: " + message)
except:
traceback.print_exc()
def on_stream_error(self, error: Exception) -> bool:
print("Received a stream error.", file=sys.stderr)
579
AWS IoT Greengrass Developer Guide, Version 2
Examples
traceback.print_exc()
return False # Return True to close stream, False to keep stream open.
def on_stream_closed(self) -> None:
print('Subscribe to topic stream closed.')
try:
ipc_client = awsiot.greengrasscoreipc.connect()
request = SubscribeToTopicRequest()
request.topic = topic
handler = StreamHandler()
operation = ipc_client.new_subscribe_to_topic(handler)
future = operation.activate(request)
try:
future.result(TIMEOUT)
print('Successfully subscribed to topic: ' + topic)
except concurrent.futures.TimeoutError as e:
print('Timeout occurred while subscribing to topic: ' + topic, file=sys.stderr)
raise e
except UnauthorizedError as e:
print('Unauthorized error while subscribing to topic: ' + topic, file=sys.stderr)
raise e
except Exception as e:
print('Exception while subscribing to topic: ' + topic, file=sys.stderr)
raise e
# Keep the main thread alive, or the process will exit.
try:
while True:
time.sleep(10)
except InterruptedError:
print('Subscribe interrupted.')
except Exception:
print('Exception occurred when using IPC.', file=sys.stderr)
traceback.print_exc()
exit(1)
Example publish/subscribe publisher (C++)
The following example recipe allows the component to publish to all topics.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.PubSubPublisherCpp",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that publishes messages.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"accessControl": {
"aws.greengrass.ipc.pubsub": {
"com.example.PubSubPublisherCpp:pubsub:1": {
"policyDescription": "Allows access to publish to all topics.",
"operations": [
"aws.greengrass#PublishToTopic"
],
"resources": [
"*"
]
580
AWS IoT Greengrass Developer Guide, Version 2
Examples
}
}
}
}
},
"Manifests": [
{
"Lifecycle": {
"Run": "{artifacts:path}/greengrassv2_pubsub_publisher"
},
"Artifacts": [
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.PubSubPublisherCpp/1.0.0/greengrassv2_pubsub_publisher",
"Permission": {
"Execute": "OWNER"
}
}
]
}
]
}
YAML
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.PubSubPublisherCpp
ComponentVersion: 1.0.0
ComponentDescription: A component that publishes messages.
ComponentPublisher: Amazon
ComponentConfiguration:
DefaultConfiguration:
accessControl:
aws.greengrass.ipc.pubsub:
com.example.PubSubPublisherCpp:pubsub:1:
policyDescription: Allows access to publish to all topics.
operations:
- aws.greengrass#PublishToTopic
resources:
- "*"
Manifests:
- Lifecycle:
Run: "{artifacts:path}/greengrassv2_pubsub_publisher"
Artifacts:
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.PubSubPublisherCpp/1.0.0/
greengrassv2_pubsub_publisher
Permission:
Execute: OWNER
The following example C++ application demonstrates how to use the publish/subscribe IPC service to
publish messages to other components.
#include <iostream>
#include <aws/crt/Api.h>
#include <aws/greengrass/GreengrassCoreIpcClient.h>
using namespace Aws::Crt;
using namespace Aws::Greengrass;
class IpcClientLifecycleHandler : public ConnectionLifecycleHandler {
581
AWS IoT Greengrass Developer Guide, Version 2
Examples
void OnConnectCallback() override {
std::cout << "OnConnectCallback" << std::endl;
}
void OnDisconnectCallback(RpcError error) override {
std::cout << "OnDisconnectCallback: " << error.StatusToString() << std::endl;
exit(-1);
}
bool OnErrorCallback(RpcError error) override {
std::cout << "OnErrorCallback: " << error.StatusToString() << std::endl;
return true;
}
};
int main() {
String message("Hello from the pub/sub publisher (C++).");
String topic("test/topic/cpp");
int timeout = 10;
ApiHandle apiHandle(g_allocator);
Io::EventLoopGroup eventLoopGroup(1);
Io::DefaultHostResolver socketResolver(eventLoopGroup, 64, 30);
Io::ClientBootstrap bootstrap(eventLoopGroup, socketResolver);
IpcClientLifecycleHandler ipcLifecycleHandler;
GreengrassCoreIpcClient ipcClient(bootstrap);
auto connectionStatus = ipcClient.Connect(ipcLifecycleHandler).get();
if (!connectionStatus) {
std::cerr << "Failed to establish IPC connection: " <<
connectionStatus.StatusToString() << std::endl;
exit(-1);
}
while (true) {
PublishToTopicRequest request;
Vector<uint8_t> messageData({message.begin(), message.end()});
BinaryMessage binaryMessage;
binaryMessage.SetMessage(messageData);
PublishMessage publishMessage;
publishMessage.SetBinaryMessage(binaryMessage);
request.SetTopic(topic);
request.SetPublishMessage(publishMessage);
PublishToTopicOperation operation = ipcClient.NewPublishToTopic();
auto activate = operation.Activate(request, nullptr);
activate.wait();
auto responseFuture = operation.GetResult();
if (responseFuture.wait_for(std::chrono::seconds(timeout)) ==
std::future_status::timeout) {
std::cerr << "Operation timed out while waiting for response from Greengrass
Core." << std::endl;
exit(-1);
}
auto response = responseFuture.get();
if (response) {
std::cout << "Successfully published to topic: " << topic << std::endl;
} else {
// An error occurred.
std::cout << "Failed to publish to topic: " << topic << std::endl;
auto errorType = response.GetResultType();
if (errorType == OPERATION_ERROR) {
auto *error = response.GetOperationError();
std::cout << "Operation error: " << error->GetMessage().value() <<
std::endl;
582
AWS IoT Greengrass Developer Guide, Version 2
Examples
} else {
std::cout << "RPC error: " << response.GetRpcError() << std::endl;
}
exit(-1);
}
std::this_thread::sleep_for(std::chrono::seconds(5));
}
return 0;
}
Example publish/subscribe subscriber (C++)
The following example recipe allows the component to subscribe to all topics.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.PubSubSubscriberCpp",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that subscribes to messages.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"accessControl": {
"aws.greengrass.ipc.pubsub": {
"com.example.PubSubSubscriberCpp:pubsub:1": {
"policyDescription": "Allows access to subscribe to all topics.",
"operations": [
"aws.greengrass#SubscribeToTopic"
],
"resources": [
"*"
]
}
}
}
}
},
"Manifests": [
{
"Lifecycle": {
"Run": "{artifacts:path}/greengrassv2_pub_sub_subscriber"
},
"Artifacts": [
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.PubSubSubscriberCpp/1.0.0/greengrassv2_pub_sub_subscriber",
"Permission": {
"Execute": "OWNER"
}
}
]
}
]
}
YAML
---
RecipeFormatVersion: '2020-01-25'
583
AWS IoT Greengrass Developer Guide, Version 2
Examples
ComponentName: com.example.PubSubSubscriberCpp
ComponentVersion: 1.0.0
ComponentDescription: A component that subscribes to messages.
ComponentPublisher: Amazon
ComponentConfiguration:
DefaultConfiguration:
accessControl:
aws.greengrass.ipc.pubsub:
com.example.PubSubSubscriberCpp:pubsub:1:
policyDescription: Allows access to subscribe to all topics.
operations:
- aws.greengrass#SubscribeToTopic
resources:
- "*"
Manifests:
- Lifecycle:
Run: "{artifacts:path}/greengrassv2_pub_sub_subscriber"
Artifacts:
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.PubSubSubscriberCpp/1.0.0/
greengrassv2_pub_sub_subscriber
Permission:
Execute: OWNER
The following example C++ application demonstrates how to use the publish/subscribe IPC service to
subscribe to messages to other components.
#include <iostream>
#include <aws/crt/Api.h>
#include <aws/greengrass/GreengrassCoreIpcClient.h>
using namespace Aws::Crt;
using namespace Aws::Greengrass;
class SubscribeResponseHandler : public SubscribeToTopicStreamHandler {
void OnStreamEvent(SubscriptionResponseMessage *response) override {
auto jsonMessage = response->GetJsonMessage();
if (jsonMessage.has_value() && jsonMessage.value().GetMessage().has_value()) {
auto messageString =
jsonMessage.value().GetMessage().value().View().WriteReadable();
std::cout << "Received new message: " << messageString << std::endl;
} else {
auto binaryMessage = response->GetBinaryMessage();
if (binaryMessage.has_value() &&
binaryMessage.value().GetMessage().has_value()) {
auto messageBytes = binaryMessage.value().GetMessage().value();
std::string messageString(messageBytes.begin(), messageBytes.end());
std::cout << "Received new message: " << messageString << std::endl;
}
}
}
bool OnStreamError(OperationError *error) override {
std::cout << "Received an operation error: ";
if (error->GetMessage().has_value()) {
std::cout << error->GetMessage().value();
}
std::cout << std::endl;
return false; // Return true to close stream, false to keep stream open.
}
void OnStreamClosed() override {
std::cout << "Subscribe to topic stream closed." << std::endl;
584
AWS IoT Greengrass Developer Guide, Version 2
Examples
}
};
class IpcClientLifecycleHandler : public ConnectionLifecycleHandler {
void OnConnectCallback() override {
std::cout << "OnConnectCallback" << std::endl;
}
void OnDisconnectCallback(RpcError error) override {
std::cout << "OnDisconnectCallback: " << error.StatusToString() << std::endl;
exit(-1);
}
bool OnErrorCallback(RpcError error) override {
std::cout << "OnErrorCallback: " << error.StatusToString() << std::endl;
return true;
}
};
int main() {
String topic("test/topic/cpp");
int timeout = 10;
ApiHandle apiHandle(g_allocator);
Io::EventLoopGroup eventLoopGroup(1);
Io::DefaultHostResolver socketResolver(eventLoopGroup, 64, 30);
Io::ClientBootstrap bootstrap(eventLoopGroup, socketResolver);
IpcClientLifecycleHandler ipcLifecycleHandler;
GreengrassCoreIpcClient ipcClient(bootstrap);
auto connectionStatus = ipcClient.Connect(ipcLifecycleHandler).get();
if (!connectionStatus) {
std::cerr << "Failed to establish IPC connection: " <<
connectionStatus.StatusToString() << std::endl;
exit(-1);
}
SubscribeToTopicRequest request;
request.SetTopic(topic);
SubscribeResponseHandler streamHandler;
SubscribeToTopicOperation operation = ipcClient.NewSubscribeToTopic(streamHandler);
auto activate = operation.Activate(request, nullptr);
activate.wait();
auto responseFuture = operation.GetResult();
if (responseFuture.wait_for(std::chrono::seconds(timeout)) ==
std::future_status::timeout) {
std::cerr << "Operation timed out while waiting for response from Greengrass Core."
<< std::endl;
exit(-1);
}
auto response = responseFuture.get();
if (response) {
std::cout << "Successfully subscribed to topic: " << topic << std::endl;
} else {
// An error occurred.
std::cout << "Failed to subscribe to topic: " << topic << std::endl;
auto errorType = response.GetResultType();
if (errorType == OPERATION_ERROR) {
auto *error = response.GetOperationError();
std::cout << "Operation error: " << error->GetMessage().value() << std::endl;
} else {
std::cout << "RPC error: " << response.GetRpcError() << std::endl;
}
exit(-1);
}
585
AWS IoT Greengrass Developer Guide, Version 2
Publish/subscribe AWS IoT Core MQTT messages
// Keep the main thread alive, or the process will exit.
while (true) {
std::this_thread::sleep_for(std::chrono::seconds(10));
}
operation.Close();
return 0;
}
Publish/subscribe AWS IoT Core MQTT messages
The AWS IoT Core MQTT messaging IPC service lets you send and receive MQTT messages to and from
AWS IoT Core. Components can publish messages to AWS IoT Core and subscribe to topics to act on
MQTT messages from other sources. For more information about the AWS IoT Core implementation of
MQTT, see MQTT in the AWS IoT Core Developer Guide.
Note
This MQTT messaging IPC service lets you exchange messages with AWS IoT Core. For more
information about how to exchange messages between components, see Publish/subscribe local
messages (p. 561).
Topics
• Authorization (p. 586)
• PublishToIoTCore (p. 587)
• SubscribeToIoTCore (p. 590)
• Examples (p. 596)
Authorization
To use AWS IoT Core MQTT messaging in a custom component, you must define authorization policies
that allows your component to send and receive messages on topics. For information about defining
authorization policies, see Authorize components to perform IPC operations (p. 552).
Authorization policies for AWS IoT Core MQTT messaging have the following properties.
IPC service identifier: aws.greengrass.ipc.mqttproxy
Operation Description Resources
Allows a component to publish
aws.greengrass#PublishToIoTCore A topic string, such as test/
messages to AWS IoT Core topic, or * to allow access to all
on the MQTT topics that you topics. This topic string supports
specify. MQTT topic wildcards (# and +).
Allows a component to subscribe A topic string, such as test/
aws.greengrass#SubscribeToIoTCore
to messages from AWS IoT Core topic, or * to allow access to all
on the topics that you specify. topics. This topic string supports
MQTT topic wildcards (# and +).
* Allows a component to publish A topic string, such as test/
and subscribe to AWS IoT Core topic, or * to allow access to all
MQTT messages for the topics topics. This topic string supports
that you specify. MQTT topic wildcards (# and +).
586
AWS IoT Greengrass Developer Guide, Version 2
PublishToIoTCore
Example Example authorization policy
The following example authorization policy allows a component to publish and subscribe to all topics.
{
"accessControl": {
"aws.greengrass.ipc.mqttproxy": {
"com.example.MyIoTCorePubSubComponent:mqttproxy:1": {
"policyDescription": "Allows access to publish/subscribe to all topics.",
"operations": [
"aws.greengrass#PublishToIoTCore",
"aws.greengrass#SubscribeToIoTCore"
],
"resources": [
"*"
]
}
}
}
}
PublishToIoTCore
Publishes an MQTT message to AWS IoT Core on a topic.
Request
This operation's request has the following parameters:
topicName (Python: topic_name)
The topic to which to publish the message.
qos
The MQTT QoS to use. This enum, QOS, has the following values:
• AT_MOST_ONCE – QoS 0. The MQTT message is delivered at most once.
• AT_LEAST_ONCE – QoS 1. The MQTT message is delivered at least once.
payload
(Optional) The message payload as a blob.
Response
This operation doesn't provide any information in its response.
Examples
The following examples demonstrate how to call this operation in custom component code.
Java
Example Example: Publish a message
Note
This example uses an IPCUtils class to create a connection to the AWS IoT Greengrass
Core IPC service. For more information, see Connect to the AWS IoT Greengrass Core IPC
service (p. 546).
587
AWS IoT Greengrass Developer Guide, Version 2
PublishToIoTCore
package com.aws.greengrass.docs.samples.ipc;
import com.aws.greengrass.docs.samples.ipc.util.IPCUtils;
import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient;
import software.amazon.awssdk.aws.greengrass.PublishToIoTCoreResponseHandler;
import software.amazon.awssdk.aws.greengrass.model.PublishToIoTCoreRequest;
import software.amazon.awssdk.aws.greengrass.model.PublishToIoTCoreResponse;
import software.amazon.awssdk.aws.greengrass.model.QOS;
import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError;
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
import java.nio.charset.StandardCharsets;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
public class PublishToIoTCore {
public static final int TIMEOUT_SECONDS = 10;
public static void main(String[] args) {
String topic = args[0];
String message = args[1];
QOS qos = QOS.get(args[2]);
try (EventStreamRPCConnection eventStreamRPCConnection =
IPCUtils.getEventStreamRpcConnection()) {
GreengrassCoreIPCClient ipcClient =
new GreengrassCoreIPCClient(eventStreamRPCConnection);
PublishToIoTCoreResponseHandler responseHandler =
PublishToIoTCore.publishBinaryMessageToTopic(ipcClient, topic,
message, qos);
CompletableFuture<PublishToIoTCoreResponse> futureResponse =
responseHandler.getResponse();
try {
futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS);
System.out.println("Successfully published to topic: " + topic);
} catch (TimeoutException e) {
System.err.println("Timeout occurred while publishing to topic: " +
topic);
} catch (ExecutionException e) {
if (e.getCause() instanceof UnauthorizedError) {
System.err.println("Unauthorized error while publishing to topic: "
+ topic);
} else {
throw e;
}
}
} catch (InterruptedException e) {
System.out.println("IPC interrupted.");
} catch (ExecutionException e) {
System.err.println("Exception occurred when using IPC.");
e.printStackTrace();
System.exit(1);
}
}
public static PublishToIoTCoreResponseHandler
publishBinaryMessageToTopic(GreengrassCoreIPCClient greengrassCoreIPCClient, String
topic, String message, QOS qos) {
PublishToIoTCoreRequest publishToIoTCoreRequest = new
PublishToIoTCoreRequest();
publishToIoTCoreRequest.setTopicName(topic);
publishToIoTCoreRequest.setPayload(message.getBytes(StandardCharsets.UTF_8));
588
AWS IoT Greengrass Developer Guide, Version 2
PublishToIoTCore
publishToIoTCoreRequest.setQos(qos);
return greengrassCoreIPCClient.publishToIoTCore(publishToIoTCoreRequest,
Optional.empty());
}
}
Python
Example Example: Publish a message
Note
This example assumes that you are using version 1.5.4 or later of the AWS IoT Device SDK
for Python v2. If you are using version 1.5.3 of the SDK, see Use AWS IoT Device SDK for
Python v2 (p. 548) for information about connecting to the AWS IoT Greengrass Core IPC
service.
import awsiot.greengrasscoreipc
import awsiot.greengrasscoreipc.client as client
from awsiot.greengrasscoreipc.model import (
QOS,
PublishToIoTCoreRequest
)
TIMEOUT = 10
ipc_client = awsiot.greengrasscoreipc.connect()
topic = "my/topic"
message = "Hello, World"
qos = QOS.AT_LEAST_ONCE
request = PublishToIoTCoreRequest()
request.topic_name = topic
request.payload = bytes(message, "utf-8")
request.qos = qos
operation = ipc_client.new_publish_to_iot_core()
operation.activate(request)
future = operation.get_response()
future.result(TIMEOUT)
C++
Example Example: Publish a message
#include <iostream>
#include <aws/crt/Api.h>
#include <aws/greengrass/GreengrassCoreIpcClient.h>
using namespace Aws::Crt;
using namespace Aws::Greengrass;
class IpcClientLifecycleHandler : public ConnectionLifecycleHandler {
void OnConnectCallback() override {
// Handle connection to IPC service.
}
void OnDisconnectCallback(RpcError error) override {
// Handle disconnection from IPC service.
}
589
AWS IoT Greengrass Developer Guide, Version 2
SubscribeToIoTCore
bool OnErrorCallback(RpcError error) override {
// Handle IPC service connection error.
return true;
}
};
int main() {
ApiHandle apiHandle(g_allocator);
Io::EventLoopGroup eventLoopGroup(1);
Io::DefaultHostResolver socketResolver(eventLoopGroup, 64, 30);
Io::ClientBootstrap bootstrap(eventLoopGroup, socketResolver);
IpcClientLifecycleHandler ipcLifecycleHandler;
GreengrassCoreIpcClient ipcClient(bootstrap);
auto connectionStatus = ipcClient.Connect(ipcLifecycleHandler).get();
if (!connectionStatus) {
std::cerr << "Failed to establish IPC connection: " <<
connectionStatus.StatusToString() << std::endl;
exit(-1);
}
String message("Hello, World!");
String topic("my/topic");
QOS qos = QOS_AT_MOST_ONCE;
int timeout = 10;
PublishToIoTCoreRequest request;
Vector<uint8_t> messageData({message.begin(), message.end()});
request.SetTopicName(topic);
request.SetPayload(messageData);
request.SetQos(qos);
PublishToIoTCoreOperation operation = ipcClient.NewPublishToIoTCore();
auto activate = operation.Activate(request, nullptr);
activate.wait();
auto responseFuture = operation.GetResult();
if (responseFuture.wait_for(std::chrono::seconds(timeout)) ==
std::future_status::timeout) {
std::cerr << "Operation timed out while waiting for response from Greengrass
Core." << std::endl;
exit(-1);
}
auto response = responseFuture.get();
if (!response) {
// Handle error.
auto errorType = response.GetResultType();
if (errorType == OPERATION_ERROR) {
auto *error = response.GetOperationError();
// Handle operation error.
} else {
// Handle RPC error.
}
}
return 0;
}
SubscribeToIoTCore
Subscribe to MQTT messages from AWS IoT Core on a topic or topic filter. The AWS IoT Greengrass Core
software removes subscriptions when the component reaches the end of its lifecycle.
590
AWS IoT Greengrass Developer Guide, Version 2
SubscribeToIoTCore
This operation is a subscription operation where you subscribe to a stream of event messages. To use
this operation, define a stream response handler with functions that handle event messages, errors, and
stream closure. For more information, see Subscribe to IPC event streams (p. 554).
Event message type: IoTCoreMessage
Request
This operation's request has the following parameters:
topicName (Python: topic_name)
The topic to which to subscribe. You can use MQTT topic wildcards (# and +) to subscribe to multiple
topics.
qos
The MQTT QoS to use. This enum, QOS, has the following values:
• AT_MOST_ONCE – QoS 0. The MQTT message is delivered at most once.
• AT_LEAST_ONCE – QoS 1. The MQTT message is delivered at least once.
Response
This operation's response has the following information:
messages
The stream of MQTT messages. This object, IoTCoreMessage, contains the following information:
message
The MQTT message. This object, MQTTMessage, contains the following information:
topicName (Python: topic_name)
The topic to which the message was published.
payload
(Optional) The message payload as a blob.
Examples
The following examples demonstrate how to call this operation in custom component code.
Java
Example Example: Subscribe to messages
Note
This example uses an IPCUtils class to create a connection to the AWS IoT Greengrass
Core IPC service. For more information, see Connect to the AWS IoT Greengrass Core IPC
service (p. 546).
package com.aws.greengrass.docs.samples.ipc;
import com.aws.greengrass.docs.samples.ipc.util.IPCUtils;
import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient;
import software.amazon.awssdk.aws.greengrass.SubscribeToIoTCoreResponseHandler;
import software.amazon.awssdk.aws.greengrass.model.*;
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
import software.amazon.awssdk.eventstreamrpc.StreamResponseHandler;
591
AWS IoT Greengrass Developer Guide, Version 2
SubscribeToIoTCore
import java.nio.charset.StandardCharsets;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
public class SubscribeToIoTCore {
public static final int TIMEOUT_SECONDS = 10;
public static void main(String[] args) {
String topic = args[0];
QOS qos = QOS.get(args[1]);
try (EventStreamRPCConnection eventStreamRPCConnection =
IPCUtils.getEventStreamRpcConnection()) {
GreengrassCoreIPCClient ipcClient =
new GreengrassCoreIPCClient(eventStreamRPCConnection);
StreamResponseHandler<IoTCoreMessage> streamResponseHandler =
new SubscriptionResponseHandler();
SubscribeToIoTCoreResponseHandler responseHandler =
SubscribeToIoTCore.subscribeToIoTCore(ipcClient, topic, qos,
streamResponseHandler);
CompletableFuture<SubscribeToIoTCoreResponse> futureResponse =
responseHandler.getResponse();
try {
futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS);
System.out.println("Successfully subscribed to topic: " + topic);
} catch (TimeoutException e) {
System.err.println("Timeout occurred while subscribing to topic: " +
topic);
} catch (ExecutionException e) {
if (e.getCause() instanceof UnauthorizedError) {
System.err.println("Unauthorized error while subscribing to topic:
" + topic);
} else {
throw e;
}
}
// Keep the main thread alive, or the process will exit.
try {
while (true) {
Thread.sleep(10000);
}
} catch (InterruptedException e) {
System.out.println("Subscribe interrupted.");
}
// To stop subscribing, close the stream.
responseHandler.closeStream();
} catch (InterruptedException e) {
System.out.println("IPC interrupted.");
} catch (ExecutionException e) {
System.err.println("Exception occurred when using IPC.");
e.printStackTrace();
System.exit(1);
}
}
public static SubscribeToIoTCoreResponseHandler
subscribeToIoTCore(GreengrassCoreIPCClient greengrassCoreIPCClient, String topic, QOS
qos, StreamResponseHandler<IoTCoreMessage> streamResponseHandler) {
SubscribeToIoTCoreRequest subscribeToIoTCoreRequest = new
SubscribeToIoTCoreRequest();
592
AWS IoT Greengrass Developer Guide, Version 2
SubscribeToIoTCore
subscribeToIoTCoreRequest.setTopicName(topic);
subscribeToIoTCoreRequest.setQos(qos);
return greengrassCoreIPCClient.subscribeToIoTCore(subscribeToIoTCoreRequest,
Optional.of(streamResponseHandler));
}
public static class SubscriptionResponseHandler implements
StreamResponseHandler<IoTCoreMessage> {
@Override
public void onStreamEvent(IoTCoreMessage ioTCoreMessage) {
try {
String topic = ioTCoreMessage.getMessage().getTopicName();
String message = new String(ioTCoreMessage.getMessage().getPayload(),
StandardCharsets.UTF_8);
System.out.printf("Received new message on topic %s: %s%n", topic,
message);
} catch (Exception e) {
System.err.println("Exception occurred while processing subscription
response " +
"message.");
e.printStackTrace();
}
}
@Override
public boolean onStreamError(Throwable error) {
System.err.println("Received a stream error.");
error.printStackTrace();
return false;
}
@Override
public void onStreamClosed() {
System.out.println("Subscribe to IoT Core stream closed.");
}
}
}
Python
Example Example: Subscribe to messages
Note
This example assumes that you are using version 1.5.4 or later of the AWS IoT Device SDK
for Python v2. If you are using version 1.5.3 of the SDK, see Use AWS IoT Device SDK for
Python v2 (p. 548) for information about connecting to the AWS IoT Greengrass Core IPC
service.
import time
import traceback
import awsiot.greengrasscoreipc
import awsiot.greengrasscoreipc.client as client
from awsiot.greengrasscoreipc.model import (
IoTCoreMessage,
QOS,
SubscribeToIoTCoreRequest
)
TIMEOUT = 10
ipc_client = awsiot.greengrasscoreipc.connect()
593
AWS IoT Greengrass Developer Guide, Version 2
SubscribeToIoTCore
class StreamHandler(client.SubscribeToIoTCoreStreamHandler):
def __init__(self):
super().__init__()
def on_stream_event(self, event: IoTCoreMessage) -> None:
try:
message = str(event.message.payload, "utf-8")
topic_name = event.message.topic_name
# Handle message.
except:
traceback.print_exc()
def on_stream_error(self, error: Exception) -> bool:
# Handle error.
return True # Return True to close stream, False to keep stream open.
def on_stream_closed(self) -> None:
# Handle close.
pass
topic = "my/topic"
qos = QOS.AT_MOST_ONCE
request = SubscribeToIoTCoreRequest()
request.topic_name = topic
request.qos = qos
handler = StreamHandler()
operation = ipc_client.new_subscribe_to_iot_core(handler)
future = operation.activate(request)
future.result(TIMEOUT)
# Keep the main thread alive, or the process will exit.
while True:
time.sleep(10)
# To stop subscribing, close the operation stream.
operation.close()
C++
Example Example: Subscribe to messages
#include <iostream>
#include <aws/crt/Api.h>
#include <aws/greengrass/GreengrassCoreIpcClient.h>
using namespace Aws::Crt;
using namespace Aws::Greengrass;
class IoTCoreResponseHandler : public SubscribeToIoTCoreStreamHandler {
void OnStreamEvent(IoTCoreMessage *response) override {
auto message = response->GetMessage();
if (message.has_value() && message.value().GetPayload().has_value()) {
auto messageBytes = message.value().GetPayload().value();
std::string messageString(messageBytes.begin(), messageBytes.end());
std::string topicName = message.value().GetTopicName().value().c_str();
// Handle message.
}
}
bool OnStreamError(OperationError *error) override {
// Handle error.
return false; // Return true to close stream, false to keep stream open.
594
AWS IoT Greengrass Developer Guide, Version 2
SubscribeToIoTCore
void OnStreamClosed() override {
// Handle close.
}
};
class IpcClientLifecycleHandler : public ConnectionLifecycleHandler {
void OnConnectCallback() override {
// Handle connection to IPC service.
}
void OnDisconnectCallback(RpcError error) override {
// Handle disconnection from IPC service.
}
bool OnErrorCallback(RpcError error) override {
// Handle IPC service connection error.
return true;
}
};
int main() {
ApiHandle apiHandle(g_allocator);
Io::EventLoopGroup eventLoopGroup(1);
Io::DefaultHostResolver socketResolver(eventLoopGroup, 64, 30);
Io::ClientBootstrap bootstrap(eventLoopGroup, socketResolver);
IpcClientLifecycleHandler ipcLifecycleHandler;
GreengrassCoreIpcClient ipcClient(bootstrap);
auto connectionStatus = ipcClient.Connect(ipcLifecycleHandler).get();
if (!connectionStatus) {
std::cerr << "Failed to establish IPC connection: " <<
connectionStatus.StatusToString() << std::endl;
exit(-1);
}
String topic("my/topic");
QOS qos = QOS_AT_MOST_ONCE;
int timeout = 10;
SubscribeToIoTCoreRequest request;
request.SetTopicName(topic);
request.SetQos(qos);
IoTCoreResponseHandler streamHandler;
SubscribeToIoTCoreOperation operation =
ipcClient.NewSubscribeToIoTCore(streamHandler);
auto activate = operation.Activate(request, nullptr);
activate.wait();
auto responseFuture = operation.GetResult();
if (responseFuture.wait_for(std::chrono::seconds(timeout)) ==
std::future_status::timeout) {
std::cerr << "Operation timed out while waiting for response from Greengrass
Core." << std::endl;
exit(-1);
}
auto response = responseFuture.get();
if (!response) {
// Handle error.
auto errorType = response.GetResultType();
if (errorType == OPERATION_ERROR) {
auto *error = response.GetOperationError();
// Handle operation error.
} else {
// Handle RPC error.
595
AWS IoT Greengrass Developer Guide, Version 2
Examples
}
exit(-1);
}
// Keep the main thread alive, or the process will exit.
while (true) {
std::this_thread::sleep_for(std::chrono::seconds(10));
}
operation.Close();
return 0;
}
Examples
Use the following examples to learn how to use the AWS IoT Core MQTT IPC service in your components.
Example AWS IoT Core MQTT publisher (C++)
The following example recipe allows the component to publish to all topics.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.IoTCorePublisherCpp",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that publishes MQTT messages to IoT Core.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"accessControl": {
"aws.greengrass.ipc.mqttproxy": {
"com.example.IoTCorePublisherCpp:mqttproxy:1": {
"policyDescription": "Allows access to publish to all topics.",
"operations": [
"aws.greengrass#PublishToIoTCore"
],
"resources": [
"*"
]
}
}
}
}
},
"Manifests": [
{
"Lifecycle": {
"Run": "{artifacts:path}/greengrassv2_iotcore_publisher"
},
"Artifacts": [
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.IoTCorePublisherCpp/1.0.0/greengrassv2_iotcore_publisher",
"Permission": {
"Execute": "OWNER"
}
}
]
}
]
596
AWS IoT Greengrass Developer Guide, Version 2
Examples
YAML
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.IoTCorePublisherCpp
ComponentVersion: 1.0.0
ComponentDescription: A component that publishes MQTT messages to IoT Core.
ComponentPublisher: Amazon
ComponentConfiguration:
DefaultConfiguration:
accessControl:
aws.greengrass.ipc.mqttproxy:
com.example.IoTCorePublisherCpp:mqttproxy:1:
policyDescription: Allows access to publish to all topics.
operations:
- aws.greengrass#PublishToIoTCore
resources:
- "*"
Manifests:
- Lifecycle:
Run: "{artifacts:path}/greengrassv2_iotcore_publisher"
Artifacts:
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.IoTCorePublisherCpp/1.0.0/
greengrassv2_iotcore_publisher
Permission:
Execute: OWNER
The following example C++ application demonstrates how to use the AWS IoT Core MQTT IPC service to
publish messages to AWS IoT Core.
#include <iostream>
#include <aws/crt/Api.h>
#include <aws/greengrass/GreengrassCoreIpcClient.h>
using namespace Aws::Crt;
using namespace Aws::Greengrass;
class IpcClientLifecycleHandler : public ConnectionLifecycleHandler {
void OnConnectCallback() override {
std::cout << "OnConnectCallback" << std::endl;
}
void OnDisconnectCallback(RpcError error) override {
std::cout << "OnDisconnectCallback: " << error.StatusToString() << std::endl;
exit(-1);
}
bool OnErrorCallback(RpcError error) override {
std::cout << "OnErrorCallback: " << error.StatusToString() << std::endl;
return true;
}
};
int main() {
String message("Hello from the Greengrass IPC MQTT publisher (C++).");
String topic("test/topic/cpp");
QOS qos = QOS_AT_LEAST_ONCE;
int timeout = 10;
597
AWS IoT Greengrass Developer Guide, Version 2
Examples
ApiHandle apiHandle(g_allocator);
Io::EventLoopGroup eventLoopGroup(1);
Io::DefaultHostResolver socketResolver(eventLoopGroup, 64, 30);
Io::ClientBootstrap bootstrap(eventLoopGroup, socketResolver);
IpcClientLifecycleHandler ipcLifecycleHandler;
GreengrassCoreIpcClient ipcClient(bootstrap);
auto connectionStatus = ipcClient.Connect(ipcLifecycleHandler).get();
if (!connectionStatus) {
std::cerr << "Failed to establish IPC connection: " <<
connectionStatus.StatusToString() << std::endl;
exit(-1);
}
while (true) {
PublishToIoTCoreRequest request;
Vector<uint8_t> messageData({message.begin(), message.end()});
request.SetTopicName(topic);
request.SetPayload(messageData);
request.SetQos(qos);
PublishToIoTCoreOperation operation = ipcClient.NewPublishToIoTCore();
auto activate = operation.Activate(request, nullptr);
activate.wait();
auto responseFuture = operation.GetResult();
if (responseFuture.wait_for(std::chrono::seconds(timeout)) ==
std::future_status::timeout) {
std::cerr << "Operation timed out while waiting for response from Greengrass
Core." << std::endl;
exit(-1);
}
auto response = responseFuture.get();
if (response) {
std::cout << "Successfully published to topic: " << topic << std::endl;
} else {
// An error occurred.
std::cout << "Failed to publish to topic: " << topic << std::endl;
auto errorType = response.GetResultType();
if (errorType == OPERATION_ERROR) {
auto *error = response.GetOperationError();
std::cout << "Operation error: " << error->GetMessage().value() <<
std::endl;
} else {
std::cout << "RPC error: " << response.GetRpcError() << std::endl;
}
exit(-1);
}
std::this_thread::sleep_for(std::chrono::seconds(5));
}
return 0;
}
Example AWS IoT Core MQTT subscriber (C++)
The following example recipe allows the component to subscribe to all topics.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.IoTCoreSubscriberCpp",
598
AWS IoT Greengrass Developer Guide, Version 2
Examples
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that subscribes to MQTT messages from IoT
Core.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"accessControl": {
"aws.greengrass.ipc.mqttproxy": {
"com.example.IoTCoreSubscriberCpp:mqttproxy:1": {
"policyDescription": "Allows access to subscribe to all topics.",
"operations": [
"aws.greengrass#SubscribeToIoTCore"
],
"resources": [
"*"
]
}
}
}
}
},
"Manifests": [
{
"Lifecycle": {
"Run": "{artifacts:path}/greengrassv2_iotcore_subscriber"
},
"Artifacts": [
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.IoTCoreSubscriberCpp/1.0.0/greengrassv2_iotcore_subscriber",
"Permission": {
"Execute": "OWNER"
}
}
]
}
]
}
YAML
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.IoTCoreSubscriberCpp
ComponentVersion: 1.0.0
ComponentDescription: A component that subscribes to MQTT messages from IoT Core.
ComponentPublisher: Amazon
ComponentConfiguration:
DefaultConfiguration:
accessControl:
aws.greengrass.ipc.mqttproxy:
com.example.IoTCoreSubscriberCpp:mqttproxy:1:
policyDescription: Allows access to subscribe to all topics.
operations:
- aws.greengrass#SubscribeToIoTCore
resources:
- "*"
Manifests:
- Lifecycle:
Run: "{artifacts:path}/greengrassv2_iotcore_subscriber"
Artifacts:
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.IoTCoreSubscriberCpp/1.0.0/
greengrassv2_iotcore_subscriber
Permission:
599
AWS IoT Greengrass Developer Guide, Version 2
Examples
Execute: OWNER
The following example C++ application demonstrates how to use the AWS IoT Core MQTT IPC service to
subscribe to messages from AWS IoT Core.
#include <iostream>
#include <aws/crt/Api.h>
#include <aws/greengrass/GreengrassCoreIpcClient.h>
using namespace Aws::Crt;
using namespace Aws::Greengrass;
class IoTCoreResponseHandler : public SubscribeToIoTCoreStreamHandler {
void OnStreamEvent(IoTCoreMessage *response) override {
auto message = response->GetMessage();
if (message.has_value() && message.value().GetPayload().has_value()) {
auto messageBytes = message.value().GetPayload().value();
std::string messageString(messageBytes.begin(), messageBytes.end());
std::string messageTopic = message.value().GetTopicName().value().c_str();
std::cout << "Received new message on topic: " << messageTopic << std::endl;
std::cout << "Message: " << messageString << std::endl;
}
}
bool OnStreamError(OperationError *error) override {
std::cout << "Received an operation error: ";
if (error->GetMessage().has_value()) {
std::cout << error->GetMessage().value();
}
std::cout << std::endl;
return false; // Return true to close stream, false to keep stream open.
}
void OnStreamClosed() override {
std::cout << "Subscribe to IoT Core stream closed." << std::endl;
}
};
class IpcClientLifecycleHandler : public ConnectionLifecycleHandler {
void OnConnectCallback() override {
std::cout << "OnConnectCallback" << std::endl;
}
void OnDisconnectCallback(RpcError error) override {
std::cout << "OnDisconnectCallback: " << error.StatusToString() << std::endl;
exit(-1);
}
bool OnErrorCallback(RpcError error) override {
std::cout << "OnErrorCallback: " << error.StatusToString() << std::endl;
return true;
}
};
int main() {
String topic("test/topic/cpp");
QOS qos = QOS_AT_LEAST_ONCE;
int timeout = 10;
ApiHandle apiHandle(g_allocator);
Io::EventLoopGroup eventLoopGroup(1);
Io::DefaultHostResolver socketResolver(eventLoopGroup, 64, 30);
600
AWS IoT Greengrass Developer Guide, Version 2
Interact with component lifecycle
Io::ClientBootstrap bootstrap(eventLoopGroup, socketResolver);
IpcClientLifecycleHandler ipcLifecycleHandler;
GreengrassCoreIpcClient ipcClient(bootstrap);
auto connectionStatus = ipcClient.Connect(ipcLifecycleHandler).get();
if (!connectionStatus) {
std::cerr << "Failed to establish IPC connection: " <<
connectionStatus.StatusToString() << std::endl;
exit(-1);
}
SubscribeToIoTCoreRequest request;
request.SetTopicName(topic);
request.SetQos(qos);
IoTCoreResponseHandler streamHandler;
SubscribeToIoTCoreOperation operation =
ipcClient.NewSubscribeToIoTCore(streamHandler);
auto activate = operation.Activate(request, nullptr);
activate.wait();
auto responseFuture = operation.GetResult();
if (responseFuture.wait_for(std::chrono::seconds(timeout)) ==
std::future_status::timeout) {
std::cerr << "Operation timed out while waiting for response from Greengrass Core."
<< std::endl;
exit(-1);
}
auto response = responseFuture.get();
if (response) {
std::cout << "Successfully subscribed to topic: " << topic << std::endl;
} else {
// An error occurred.
std::cout << "Failed to subscribe to topic: " << topic << std::endl;
auto errorType = response.GetResultType();
if (errorType == OPERATION_ERROR) {
auto *error = response.GetOperationError();
std::cout << "Operation error: " << error->GetMessage().value() << std::endl;
} else {
std::cout << "RPC error: " << response.GetRpcError() << std::endl;
}
exit(-1);
}
// Keep the main thread alive, or the process will exit.
while (true) {
std::this_thread::sleep_for(std::chrono::seconds(10));
}
operation.Close();
return 0;
}
Interact with component lifecycle
Use the component lifecycle IPC service to:
• Update the component state on the core device.
• Subscribe to component state updates.
• Prevent the nucleus from stopping the component to apply an update during a deployment.
• Pause and resume component processes.
601
AWS IoT Greengrass Developer Guide, Version 2
Authorization
Topics
• Authorization (p. 602)
• UpdateState (p. 603)
• SubscribeToComponentUpdates (p. 603)
• DeferComponentUpdate (p. 604)
• PauseComponent (p. 605)
• ResumeComponent (p. 605)
Authorization
To pause or resume other components from a custom component, you must define authorization policies
that allows your component to manage other components. For information about defining authorization
policies, see Authorize components to perform IPC operations (p. 552).
Authorization policies for component lifecycle management have the following properties.
IPC service identifier: aws.greengrass.ipc.lifecycle
Operation Description Resources
Allows a component to pause
aws.greengrass#PauseComponent A component name, or * to
the components that you allow access to all components.
specify.
Allows a component to resume
aws.greengrass#ResumeComponent A component name, or * to
the components that you allow access to all components.
specify.
* Allows a component to pause A component name, or * to
and resume the components allow access to all components.
that you specify.
Example Example authorization policy
The following example authorization policy allows a component to pause and resume all components.
{
"accessControl": {
"aws.greengrass.ipc.lifecycle": {
"com.example.MyLocalLifecycleComponent:lifecycle:1": {
"policyDescription": "Allows access to pause/resume all components.",
"operations": [
"aws.greengrass#PauseComponent",
"aws.greengrass#ResumeComponent"
],
"resources": [
"*"
]
}
}
}
}
602
AWS IoT Greengrass Developer Guide, Version 2
UpdateState
UpdateState
Update the state of the component on the core device.
Request
This operation's request has the following parameters:
state
The state to set. This enum, LifecycleState, has the following values:
• RUNNING
• ERRORED
Response
This operation doesn't provide any information in its response.
SubscribeToComponentUpdates
Subscribe to receive notifications before the AWS IoT Greengrass Core software updates a component.
The notification specifies whether or not the nucleus will restart as part of the update.
The nucleus sends update notifications only if the deployment's component update policy specifies to
notify components. The default behavior is to notify components. For more information, see Create
deployments (p. 493) and the DeploymentComponentUpdatePolicy object that you can provide when
you call the CreateDeployment operation.
Important
Local deployments don't notify components before updates.
This operation is a subscription operation where you subscribe to a stream of event messages. To use
this operation, define a stream response handler with functions that handle event messages, errors, and
stream closure. For more information, see Subscribe to IPC event streams (p. 554).
Event message type: ComponentUpdatePolicyEvents
Request
This operation's request doesn't have any parameters.
Response
This operation's response has the following information:
messages
The stream of notification messages. This object, ComponentUpdatePolicyEvents, contains the
following information:
preUpdateEvent (Python: pre_update_event)
(Optional) An event that indicates that the nucleus wants to update a component. You can
respond with the DeferComponentUpdate (p. 604) operation to acknowledge or defer the
603
AWS IoT Greengrass Developer Guide, Version 2
DeferComponentUpdate
update until your component is ready to restart. This object, PreComponentUpdateEvent,
contains the following information:
deploymentId (Python: deployment_id)
The ID of the AWS IoT Greengrass deployment that updates the component.
isGgcRestarting (Python: is_ggc_restarting)
Whether or not the nucleus needs to restart to apply the update.
postUpdateEvent (Python: post_update_event)
(Optional) An event that indicates that the nucleus updated a component. This object,
PostComponentUpdateEvent, contains the following information:
deploymentId (Python: deployment_id)
The ID of the AWS IoT Greengrass deployment that updated the component.
DeferComponentUpdate
Acknowledge or defer a component update that you discover with
SubscribeToComponentUpdates (p. 603). You specify the amount of time to wait before the nucleus
checks again if your component is ready to let the component update proceed. You can also use this
operation to tell the nucleus that your component is ready for the update.
If a component doesn't respond to the component update notification, the nucleus waits the amount
of time that you specify in the deployment's component update policy. After that timeout, the nucleus
proceeds with the deployment. The default component update timeout is 60 seconds. For more
information, see Create deployments (p. 493) and the DeploymentComponentUpdatePolicy object that
you can provide when you call the CreateDeployment operation.
Request
This operation's request has the following parameters:
deploymentId (Python: deployment_id)
The ID of the AWS IoT Greengrass deployment to defer.
message
(Optional) The name of the component for which to defer updates.
Defaults to the name of the component that makes the request.
recheckAfterMs (Python: recheck_after_ms)
The amount of time in milliseconds for which to defer the update. The nucleus waits for this
amount of time and then sends another PreComponentUpdateEvent that you can discover with
SubscribeToComponentUpdates (p. 603).
Specify 0 to acknowledge the update. This tells the nucleus that your component is ready for the
update.
Defaults to zero milliseconds, which means to acknowledge the update.
Response
This operation doesn't provide any information in its response.
604
AWS IoT Greengrass Developer Guide, Version 2
PauseComponent
PauseComponent
This feature is available for v2.4.0 and later of the Greengrass nucleus component (p. 181). AWS IoT
Greengrass doesn't currently support this feature on Windows core devices.
Pauses a component's processes on the core device. To resume a component, use the
ResumeComponent (p. 605) operation.
You can pause only generic components. If you try to pause any other type of component, this operation
throws an InvalidRequestError.
Note
This operation can't pause containerized processes, such as Docker containers. To pause and
resume a Docker container, you can use the docker pause and docker resume commands.
This operation doesn't pause component dependencies or components that depend on the component
that you pause. Consider this behavior when you pause a component that is a dependency of another
component, because the dependent component might encounter issues when its dependency is paused.
When you restart or shut down a paused component, such as through a deployment, the Greengrass
nucleus resumes the component and runs its shutdown lifecycle.
Important
To use this operation, you must define an authorization policy that grants permission to use this
operation. For more information, see Authorization (p. 602).
Minimum SDK versions
The following table lists the minimum versions of the AWS IoT Device SDK that you must use to pause
and resume components.
SDK Minimum version
AWS IoT Device SDK for Java v2 v1.4.3
AWS IoT Device SDK for Python v1.6.2
v2
AWS IoT Device SDK for C++ v2 v1.13.1
Request
This operation's request has the following parameters:
componentName (Python: component_name)
The name of the component to pause, which must be a generic component. For more information,
see Component types (p. 441).
Response
This operation doesn't provide any information in its response.
ResumeComponent
This feature is available for v2.4.0 and later of the Greengrass nucleus component (p. 181). AWS IoT
Greengrass doesn't currently support this feature on Windows core devices.
605
AWS IoT Greengrass Developer Guide, Version 2
Interact with component configuration
Resumes a component's processes on the core device. To pause a component, use the
PauseComponent (p. 605) operation.
You can resume only paused components. If you try to resume a component that isn't paused, this
operation throws an InvalidRequestError.
Important
To use this operation, you must define an authorization policy that grants permission to do so.
For more information, see Authorization (p. 602).
Minimum SDK versions
The following table lists the minimum versions of the AWS IoT Device SDK that you must use to pause
and resume components.
SDK Minimum version
AWS IoT Device SDK for Java v2 v1.4.3
AWS IoT Device SDK for Python v1.6.2
v2
AWS IoT Device SDK for C++ v2 v1.13.1
Request
This operation's request has the following parameters:
componentName (Python: component_name)
The name of the component to resume.
Response
This operation doesn't provide any information in its response.
Interact with component configuration
The component configuration IPC service lets you do the following:
• Get and set component configuration parameters.
• Subscribe to component configuration updates.
• Validate component configuration updates before the nucleus applies them.
Topics
• GetConfiguration (p. 607)
• UpdateConfiguration (p. 607)
• SubscribeToConfigurationUpdate (p. 608)
• SubscribeToValidateConfigurationUpdates (p. 609)
606
AWS IoT Greengrass Developer Guide, Version 2
GetConfiguration
• SendConfigurationValidityReport (p. 610)
GetConfiguration
Gets a configuration value for a component on the core device. You specify the key path for which to get
a configuration value.
Request
This operation's request has the following parameters:
componentName (Python: component_name)
(Optional) The name of the component.
Defaults to the name of the component that makes the request.
keyPath (Python: key_path)
The key path to the configuration value. Specify a list where each entry is the key for a single level in
the configuration object. For example, specify ["mqtt", "port"] to get the value of port in the
following configuration.
{
"mqtt": {
"port": 443
}
}
Response
This operation's response has the following information:
componentName (Python: component_name)
The name of the component.
value
The requested configuration as an object.
UpdateConfiguration
Updates a configuration value for a component on the core device.
Request
This operation's request has the following parameters:
keyPath (Python: key_path)
(Optional) The key path to the container node (the object) to update. Specify a list where each entry
is the key for a single level in the configuration object. For example, specify the key path ["mqtt"]
and the merge value { "port": 443 } to set the value of port in the following configuration.
607
AWS IoT Greengrass Developer Guide, Version 2
SubscribeToConfigurationUpdate
{
"mqtt": {
"port": 443
}
}
The key path must specify a container node (an object) in the configuration. If the node doesn't
exist in the component's configuration, this operation creates it and sets its value to the object in
valueToMerge.
Defaults to the root of the configuration object.
timestamp
The current Unix epoch time in milliseconds. This operation uses this timestamp to resolve
concurrent updates to the key. If the key in the component configuration has a greater timestamp
than the timestamp in the request, then the request fails.
valueToMerge (Python: value_to_merge)
The configuration object to merge at the location that you specify in keyPath. For more
information, see Update component configurations (p. 500).
Response
This operation doesn't provide any information in its response.
SubscribeToConfigurationUpdate
Subscribe to receive notifications when a component's configuration updates. When you subscribe to a
key, you receive a notification when any child of that key updates.
This operation is a subscription operation where you subscribe to a stream of event messages. To use
this operation, define a stream response handler with functions that handle event messages, errors, and
stream closure. For more information, see Subscribe to IPC event streams (p. 554).
Event message type: ConfigurationUpdateEvents
Request
This operation's request has the following parameters:
componentName (Python: component_name)
(Optional) The name of the component.
Defaults to the name of the component that makes the request.
keyPath (Python: key_path)
The key path to the configuration value for which to subscribe. Specify a list where each entry is the
key for a single level in the configuration object. For example, specify ["mqtt", "port"] to get
the value of port in the following configuration.
{
"mqtt": {
"port": 443
608
AWS IoT Greengrass Developer Guide, Version 2
SubscribeToValidateConfigurationUpdates
}
}
Response
This operation's response has the following information:
messages
The stream of notification messages. This object, ConfigurationUpdateEvents, contains the
following information:
configurationUpdateEvent (Python: configuration_update_event)
The configuration update event. This object, ConfigurationUpdateEvent, contains the
following information:
componentName (Python: component_name)
The name of the component.
keyPath (Python: key_path)
The key path to the configuration value that updated.
SubscribeToValidateConfigurationUpdates
Subscribe to receive notifications before this component's configuration updates. This lets components
validate updates to their own configuration. Use the SendConfigurationValidityReport (p. 610)
operation to tell the nucleus whether or not the configuration is valid.
Important
Local deployments don't notify components of updates.
This operation is a subscription operation where you subscribe to a stream of event messages. To use
this operation, define a stream response handler with functions that handle event messages, errors, and
stream closure. For more information, see Subscribe to IPC event streams (p. 554).
Event message type: ValidateConfigurationUpdateEvents
Request
This operation's request doesn't have any parameters.
Response
This operation's response has the following information:
messages
The stream of notification messages. This object, ValidateConfigurationUpdateEvents,
contains the following information:
validateConfigurationUpdateEvent (Python: validate_configuration_update_event)
The configuration update event. This object, ValidateConfigurationUpdateEvent,
contains the following information:
609
AWS IoT Greengrass Developer Guide, Version 2
SendConfigurationValidityReport
deploymentId (Python: deployment_id)
The ID of the AWS IoT Greengrass deployment that updates the component.
configuration
The object that contains the new configuration.
SendConfigurationValidityReport
Tell the nucleus whether or not a configuration update to this component is valid. The
deployment fails if you tell the nucleus that the new configuration isn't valid. Use the
SubscribeToValidateConfigurationUpdates (p. 609) operation to subscribe to validate configuration
updates.
If a component doesn't respond to a validate configuration update notification, the nucleus waits the
amount of time that you specify in the deployment's configuration validation policy. After that timeout,
the nucleus proceeds with the deployment. The default component validation timeout is 20 seconds. For
more information, see Create deployments (p. 493) and the ConfigurationValidationPolicy object that
you can provide when you call the CreateDeployment operation.
Request
This operation's request has the following parameters:
configurationValidityReport (Python: configuration_validity_report)
The report that tells the nucleus whether or not the configuration update is valid. This object,
ConfigurationValidityReport, contains the following information:
status
The validity status. This enum, ConfigurationValidityStatus, has the following values:
• ACCEPTED – The configuration is valid and the nucleus can apply it to this component.
• REJECTED – The configuration isn't valid and the deployment fails.
deploymentId (Python: deployment_id)
The ID of the AWS IoT Greengrass deployment that requested the configuration update.
message
(Optional) A message that reports why the configuration isn't valid.
Response
This operation doesn't provide any information in its response.
Retrieve secret values
Use the secret manager IPC service to retrieve secret values from secrets on the core device. You use the
secret manager component (p. 374) to deploy encrypted secrets to core devices. Then, you can use an
IPC operation to decrypt the secret and use its value in your custom components.
Topics
• Authorization (p. 611)
610
AWS IoT Greengrass Developer Guide, Version 2
Authorization
• GetSecretValue (p. 611)
• Examples (p. 614)
Authorization
To use secret manager in a custom component, you must define authorization policies that allow your
component to get the value of secrets that you store on the core device. For information about defining
authorization policies, see Authorize components to perform IPC operations (p. 552).
Authorization policies for secret manager have the following properties.
IPC service identifier: aws.greengrass.SecretManager
Operation Description Resources
Allows a component to get
aws.greengrass#GetSecretValue A Secrets Manager secret ARN,
or * the value of secrets that are or * to allow access to all
encrypted on the core device. secrets.
Example Example authorization policy
The following example authorization policy allows a component to get the value of any secret on the
core device.
Note
We recommend that in a production environment, you reduce the scope of the authorization
policy, so that the component retrieves only the secrets that it uses. You can change the *
wildcard to a list of secret ARNs when you deploy the component.
{
"accessControl": {
"aws.greengrass.SecretManager": {
"com.example.MySecretComponent:secrets:1": {
"policyDescription": "Allows access to a secret.",
"operations": [
"aws.greengrass#GetSecretValue"
],
"resources": [
"*"
]
}
}
}
}
GetSecretValue
Gets the value of a secret that you store on the core device.
This operation is similar to the Secrets Manager operation that you can use to get the value of a secret in
the AWS Cloud. For more information, see GetSecretValue in the AWS Secrets Manager API Reference.
Request
This operation's request has the following parameters:
611
AWS IoT Greengrass Developer Guide, Version 2
GetSecretValue
secretId
The name of the secret to get. You can specify either the Amazon Resource Name (ARN) or the
friendly name of the secret.
versionId
(Optional) The ID of the version to get.
You can specify either versionId or versionStage.
If you don't specify versionId or versionStage, this operation defaults to the version with the
AWSCURRENT label.
versionStage
(Optional) The staging label of the version to get.
You can specify either versionId or versionStage.
If you don't specify versionId or versionStage, this operation defaults to the version with the
AWSCURRENT label.
Response
This operation's response has the following information:
secretId
The ID of the secret.
versionId
The ID of this version of the secret.
versionStage
The list of staging labels attached to this version of the secret.
secretValue
The value of this version of the secret. This object, SecretValue, contains the following
information.
secretString
The decrypted part of the protected secret information that you provided to Secrets Manager as
a string.
secretBinary
(Optional) The decrypted part of the protected secret information that you provided to Secrets
Manager as binary data in the form of a byte array. This property contains the binary data as a
base64-encoded string.
This property isn't used if you created the secret in the Secrets Manager console.
Examples
The following examples demonstrate how to call this operation in custom component code.
612
AWS IoT Greengrass Developer Guide, Version 2
GetSecretValue
Java
Example Example: Get a secret value
Note
This example uses an IPCUtils class to create a connection to the AWS IoT Greengrass
Core IPC service. For more information, see Connect to the AWS IoT Greengrass Core IPC
service (p. 546).
package com.aws.greengrass.docs.samples.ipc;
import com.aws.greengrass.docs.samples.ipc.util.IPCUtils;
import software.amazon.awssdk.aws.greengrass.GetSecretValueResponseHandler;
import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient;
import software.amazon.awssdk.aws.greengrass.model.GetSecretValueRequest;
import software.amazon.awssdk.aws.greengrass.model.GetSecretValueResponse;
import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError;
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
public class GetSecretValue {
public static final int TIMEOUT_SECONDS = 10;
public static void main(String[] args) {
String secretArn = args[0];
String versionStage = args[1];
try (EventStreamRPCConnection eventStreamRPCConnection =
IPCUtils.getEventStreamRpcConnection()) {
GreengrassCoreIPCClient ipcClient =
new GreengrassCoreIPCClient(eventStreamRPCConnection);
GetSecretValueResponseHandler responseHandler =
GetSecretValue.getSecretValue(ipcClient, secretArn, versionStage);
CompletableFuture<GetSecretValueResponse> futureResponse =
responseHandler.getResponse();
try {
GetSecretValueResponse response = futureResponse.get(TIMEOUT_SECONDS,
TimeUnit.SECONDS);
response.getSecretValue().postFromJson();
String secretString = response.getSecretValue().getSecretString();
System.out.println("Successfully retrieved secret value: " +
secretString);
} catch (TimeoutException e) {
System.err.println("Timeout occurred while retrieving secret: " +
secretArn);
} catch (ExecutionException e) {
if (e.getCause() instanceof UnauthorizedError) {
System.err.println("Unauthorized error while retrieving secret: " +
secretArn);
} else {
throw e;
}
}
} catch (InterruptedException e) {
System.out.println("IPC interrupted.");
} catch (ExecutionException e) {
System.err.println("Exception occurred when using IPC.");
e.printStackTrace();
System.exit(1);
}
613
AWS IoT Greengrass Developer Guide, Version 2
Examples
public static GetSecretValueResponseHandler getSecretValue(GreengrassCoreIPCClient
greengrassCoreIPCClient, String secretArn, String versionStage) {
GetSecretValueRequest getSecretValueRequest = new GetSecretValueRequest();
getSecretValueRequest.setSecretId(secretArn);
getSecretValueRequest.setVersionStage(versionStage);
return greengrassCoreIPCClient.getSecretValue(getSecretValueRequest,
Optional.empty());
}
}
Python
Example Example: Get a secret value
Note
This example assumes that you are using version 1.5.4 or later of the AWS IoT Device SDK
for Python v2. If you are using version 1.5.3 of the SDK, see Use AWS IoT Device SDK for
Python v2 (p. 548) for information about connecting to the AWS IoT Greengrass Core IPC
service.
import json
import awsiot.greengrasscoreipc
from awsiot.greengrasscoreipc.model import (
GetSecretValueRequest,
GetSecretValueResponse,
UnauthorizedError
)
secret_id = 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyGreengrassSecret-
abcdef'
TIMEOUT = 10
ipc_client = awsiot.greengrasscoreipc.connect()
request = GetSecretValueRequest()
request.secret_id = secret_id
request.version_stage = 'AWSCURRENT'
operation = ipc_client.new_get_secret_value()
operation.activate(request)
futureResponse = operation.get_response()
response = futureResponse.result(TIMEOUT)
secret_json = json.loads(response.secret_value.secret_string)
# Handle secret value.
Examples
Use the following examples to learn how to use the secret manager IPC service in your components.
Example: Print secret (Python)
This example component prints the value of a secret that you deploy to the core device.
Important
This example component prints the value of a secret, so use it only with secrets that store test
data. Don't use this component to print the value of a secret that stores important information.
Topics
614
AWS IoT Greengrass Developer Guide, Version 2
Examples
• Recipe (p. 615)
• Artifacts (p. 616)
• Usage (p. 617)
Recipe
The following example recipe defines a secret ARN configuration parameter and allows the component
to get the value of any secret on the core device.
Note
We recommend that in a production environment, you reduce the scope of the authorization
policy, so that the component retrieves only the secrets that it uses. You can change the *
wildcard to a list of secret ARNs when you deploy the component.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.PrintSecret",
"ComponentVersion": "1.0.0",
"ComponentDescription": "Prints the value of an AWS Secrets Manager secret.",
"ComponentPublisher": "Amazon",
"ComponentDependencies": {
"aws.greengrass.SecretManager": {
"VersionRequirement": "^2.0.0",
"DependencyType": "HARD"
}
},
"ComponentConfiguration": {
"DefaultConfiguration": {
"SecretArn": "",
"accessControl": {
"aws.greengrass.SecretManager": {
"com.example.PrintSecret:secrets:1": {
"policyDescription": "Allows access to a secret.",
"operations": [
"aws.greengrass#GetSecretValue"
],
"resources": [
"*"
]
}
}
}
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"Install": "python3 -m pip install --user awsiotsdk",
"Run": "python3 -u {artifacts:path}/print_secret.py \"{configuration:/
SecretArn}\""
}
},
{
"Platform": {
"os": "windows"
},
"Lifecycle": {
"Install": "py -3 -m pip install --user awsiotsdk",
615
AWS IoT Greengrass Developer Guide, Version 2
Examples
"Run": "py -3 -u {artifacts:path}/print_secret.py \"{configuration:/
SecretArn}\""
}
}
]
}
YAML
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.PrintSecret
ComponentVersion: 1.0.0
ComponentDescription: Prints the value of a Secrets Manager secret.
ComponentPublisher: Amazon
ComponentDependencies:
aws.greengrass.SecretManager:
VersionRequirement: "^2.0.0"
DependencyType: HARD
ComponentConfiguration:
DefaultConfiguration:
SecretArn: ''
accessControl:
aws.greengrass.SecretManager:
com.example.PrintSecret:secrets:1:
policyDescription: Allows access to a secret.
operations:
- aws.greengrass#GetSecretValue
resources:
- "*"
Manifests:
- Platform:
os: linux
Lifecycle:
Install: python3 -m pip install --user awsiotsdk
Run: python3 -u {artifacts:path}/print_secret.py "{configuration:/SecretArn}"
- Platform:
os: windows
Lifecycle:
Install: py -3 -m pip install --user awsiotsdk
Run: py -3 -u {artifacts:path}/print_secret.py "{configuration:/SecretArn}"
Artifacts
The following example Python application demonstrates how to use the secret manager IPC service to
get the value of a secret on the core device.
import concurrent.futures
import json
import sys
import traceback
import awsiot.greengrasscoreipc
from awsiot.greengrasscoreipc.model import (
GetSecretValueRequest,
GetSecretValueResponse,
UnauthorizedError
)
TIMEOUT = 10
if len(sys.argv) == 1:
616
AWS IoT Greengrass Developer Guide, Version 2
Examples
print('Provide SecretArn in the component configuration.', file=sys.stdout)
exit(1)
secret_id = sys.argv[1]
try:
ipc_client = awsiot.greengrasscoreipc.connect()
request = GetSecretValueRequest()
request.secret_id = secret_id
operation = ipc_client.new_get_secret_value()
operation.activate(request)
futureResponse = operation.get_response()
try:
response = futureResponse.result(TIMEOUT)
secret_json = json.loads(response.secret_value.secret_string)
print('Successfully got secret: ' + secret_id)
print('Secret value: ' + str(secret_json))
except concurrent.futures.TimeoutError:
print('Timeout occurred while getting secret: ' + secret_id, file=sys.stderr)
except UnauthorizedError as e:
print('Unauthorized error while getting secret: ' + secret_id, file=sys.stderr)
raise e
except Exception as e:
print('Exception while getting secret: ' + secret_id, file=sys.stderr)
raise e
except Exception:
print('Exception occurred when using IPC.', file=sys.stderr)
traceback.print_exc()
exit(1)
Usage
You can use this example component with the secret manager component (p. 374) to deploy and print
the value of a secret on your core device.
To create, deploy, and print a test secret
1. Create a Secrets Manager secret with test data.
Linux or Unix
aws secretsmanager create-secret \
--name MyTestGreengrassSecret \
--secret-string '{"my-secret-key": "my-secret-value"}'
Windows Command Prompt (CMD)
aws secretsmanager create-secret ^
--name MyTestGreengrassSecret ^
--secret-string '{"my-secret-key": "my-secret-value"}'
PowerShell
aws secretsmanager create-secret `
--name MyTestGreengrassSecret `
--secret-string '{"my-secret-key": "my-secret-value"}'
Save the ARN of the secret to use in the following steps.
617
AWS IoT Greengrass Developer Guide, Version 2
Interact with local shadows
For more information, see Creating a secret in the AWS Secrets Manager User Guide.
2. Deploy the secret manager component (p. 374) (aws.greengrass.SecretManager) with the
following configuration merge update. Specify the ARN of the secret that you created earlier.
{
"cloudSecrets": [
{
"arn": "arn:aws:secretsmanager:us-
west-2:123456789012:secret:MyTestGreengrassSecret-abcdef"
}
]
}
For more information, see Deploy AWS IoT Greengrass components to devices (p. 491) or the
Greengrass CLI deployment command (p. 433).
3. Create and deploy the example component in this section with the following configuration merge
update. Specify the ARN of the secret that you created earlier.
{
"SecretArn": "arn:aws:secretsmanager:us-
west-2:123456789012:secret:MyTestGreengrassSecret",
"accessControl": {
"aws.greengrass.SecretManager": {
"com.example.PrintSecret:secrets:1": {
"policyDescription": "Allows access to a secret.",
"operations": [
"aws.greengrass#GetSecretValue"
],
"resources": [
"arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestGreengrassSecret-
abcdef"
]
}
}
}
}
For more information, see Create AWS IoT Greengrass components (p. 442)
4. View the AWS IoT Greengrass Core software logs to verify that the deployments succeed, and
view the com.example.PrintSecret component log to see the secret value printed. For more
information, see Monitor AWS IoT Greengrass logs (p. 506).
Interact with local shadows
Use the shadow IPC service to interact with local shadows on a device. The device you choose to interact
with can be your core device or a connected client device.
Include the shadow manager component (p. 383) as a dependency in your custom component. You
can then use IPC operations in your custom components to interact with local shadows on your device
through the shadow manager. To enable custom components to react to changes in local shadow states,
you can also use the publish/subscribe IPC service to subscribe to shadow events. For more information
about using the publish/subscribe service, see the Publish/subscribe local messages (p. 561).
Topics
• Minimum SDK versions (p. 619)
• Authorization (p. 619)
618
AWS IoT Greengrass Developer Guide, Version 2
Minimum SDK versions
• GetThingShadow (p. 622)
• UpdateThingShadow (p. 626)
• DeleteThingShadow (p. 630)
• ListNamedShadowsForThing (p. 633)
Minimum SDK versions
The following table lists the minimum versions of the AWS IoT Device SDK that you must use to interact
with local shadows.
SDK Minimum version
AWS IoT Device SDK for Java v2 v1.4.0
AWS IoT Device SDK for Python v1.6.0
v2
AWS IoT Device SDK for C++ v2 v1.13.0
Authorization
To use the shadow IPC service in a custom component, you must define authorization policies that allow
your component to interact with shadows. For information about defining authorization policies, see
Authorize components to perform IPC operations (p. 552).
Authorization policies for shadow interaction have the following properties.
IPC service identifier: aws.greengrass.ShadowManager
Operation Description Resources
Allows a component to retrieve
aws.greengrass#GetThingShadow One of the following strings:
the shadow of a thing.
• $aws/things/thingName/
shadow/, to allow access to
the classic device shadow
• $aws/things/thingName/
shadow/name/shadowName,
to allow access to a named
shadow
• *, to allow access to all topics.
Allows a component to update
aws.greengrass#UpdateThingShadow One of the following strings:
the shadow of a thing.
• $aws/things/thingName/
shadow/, to allow access to
the classic device shadow
• $aws/things/thingName/
shadow/name/shadowName,
to allow access to a named
shadow
• *, to allow access to all topics.
619
AWS IoT Greengrass Developer Guide, Version 2
Authorization
Operation Description Resources
Allows a component to delete
aws.greengrass#DeleteThingShadow One of the following strings:
the shadow of a thing.
• $aws/things/thingName/
shadow/, to allow access to
the classic device shadow
• $aws/things/thingName/
shadow/name/shadowName,
to allow access to a named
shadow
• *, to allow access to all topics.
Allows a component to retrieve
aws.greengrass#ListNamedShadowsForThing A thing name string that allows
the list of named shadows for a access to the thing to list its
thing. shadows.
Use * to allow access to things.
IPC service identifier: aws.greengrass.ipc.pubsub
Operation Description Resources
Allows a component to subscribe One of the following topic
aws.greengrass#SubscribeToTopic
to messages for the topics that strings:
you specify.
• shadowTopicPrefix/get/
accepted
• shadowTopicPrefix/get/
rejected
• shadowTopicPrefix/
delete/accepted
• shadowTopicPrefix/
delete/rejected
• shadowTopicPrefix/
update/accepted
• shadowTopicPrefix/
update/delta
• shadowTopicPrefix/
update/rejected
The value of the topic prefix
shadowTopicPrefix depends
on the type of shadow:
• Classic shadow: $aws/
things/thingName/shadow
• Named shadow: $aws/
things/thingName/
shadow/name/shadowName
Use * to allow access to all
topics. This topic string doesn't
620
AWS IoT Greengrass Developer Guide, Version 2
Authorization
Operation Description Resources
support MQTT topic wildcards (#
and +).
Example Example authorization policy
The following example authorization policy allows the component
com.example.MyShadowInteractionComponent to interact with the classic device shadow and the
named shadow myNamedShadow for the device MyThingName. This policy also allows this component to
receive messages on local topics for these shadows.
JSON
{
"accessControl": {
"aws.greengrass.ShadowManager": {
"com.example.MyShadowInteractionComponent:shadow:1": {
"policyDescription": "Allows access to shadows",
"operations": [
"aws.greengrass#GetThingShadow",
"aws.greengrass#UpdateThingShadow",
"aws.greengrass#DeleteThingShadow"
],
"resources": [
"$aws/things/MyThingName/shadow",
"$aws/things/MyThingName/shadow/name/myNamedShadow"
]
},
"com.example.MyShadowInteractionComponent:shadow:2": {
"policyDescription": "Allows access to things with shadows",
"operations": [
"aws.greengrass#ListNamedShadowsForThing"
],
"resources": [
"MyThingName"
]
}
},
"aws.greengrass.ipc.pubsub": {
"com.example.MyShadowInteractionComponent:pubsub:1": {
"policyDescription": "Allows access to shadow pubsub topics",
"operations": [
"aws.greengrass#SubscribeToTopic"
],
"resources": [
"$aws/things/MyThingName/shadow/get/accepted",
"$aws/things/MyThingName/shadow/name/myNamedShadow/get/accepted"
]
}
}
}
}
YAML
accessControl:
aws.greengrass.ShadowManager:
'com.example.MyShadowInteractionComponent:shadow:1':
policyDescription: 'Allows access to shadows'
operations:
- 'aws.greengrass#GetThingShadow'
621
AWS IoT Greengrass Developer Guide, Version 2
GetThingShadow
- 'aws.greengrass#UpdateThingShadow'
- 'aws.greengrass#DeleteThingShadow'
resources:
- $aws/things/MyThingName/shadow
- $aws/things/MyThingName/shadow/name/myNamedShadow
'com.example.MyShadowInteractionComponent:shadow:2':
policyDescription: 'Allows access to things with shadows'
operations:
- 'aws.greengrass#ListNamedShadowsForThing'
resources:
- MyThingName
aws.greengrass.ipc.pubsub:
'com.example.MyShadowInteractionComponent:pubsub:1':
policyDescription: 'Allows access to shadow pubsub topics'
operations:
- 'aws.greengrass#SubscribeToTopic'
resources:
- $aws/things/MyThingName/shadow/get/accepted
- $aws/things/MyThingName/shadow/name/myNamedShadow/get/accepted
GetThingShadow
Get the shadow for a specified thing.
Request
This operation's request has the following parameters:
thingName (Python: thing_name)
The name of the thing.
Type: string
shadowName (Python: shadow_name)
The name of the shadow. To specify the thing's classic shadow, set this parameter to an empty string
("").
Warning
The AWS IoT Greengrass service uses the AWSManagedGreengrassV2Deployment named
shadow to manage deployments that target individual core devices. This named shadow
is reserved for use by the AWS IoT Greengrass service. Do not update or delete this named
shadow.
Type: string
Response
This operation's response has the following information:
payload
The response state document as a blob.
Type: object that contains the following information:
state
The state information.
622
AWS IoT Greengrass Developer Guide, Version 2
GetThingShadow
This object contains the following information.
desired
The state properties and values requested to be updated in the device.
Type: map of key-value pairs
reported
The state properties and values reported by the device.
Type: map of key-value pairs
delta
The difference between the desired and reported state properties and values. This property
is present only if the desired and reported states are different.
Type: map of key-value pairs
metadata
The timestamps for each attribute in the desired and reported sections so that you can
determine when the state was updated.
Type: string
timestamp
The epoch date and time that the response was generated.
Type: integer
clientToken (Python: clientToken)
The token that is used to match the request and corresponding response
Type: string
version
The version of the local shadow document.
Type: integer
Errors
This operation can return the following errors.
InvalidArgumentsError
The local shadow service is unable to validate the request parameters. This can occur if the request
contains malformed JSON or unsupported characters.
ResourceNotFoundError
The requested local shadow document can't be found.
ServiceError
An internal service error occurred, or the number of requests to the IPC service exceeded the limits
specified in the maxLocalRequestsPerSecondPerThing and maxTotalLocalRequestsRate
configuration parameters in the shadow manager component.
623
AWS IoT Greengrass Developer Guide, Version 2
GetThingShadow
UnauthorizedError
The component's authorization policy doesn't include required permissions for this operation.
Examples
The following examples demonstrate how to call this operation in custom component code.
Java
Example Example: Get a thing shadow
Note
This example uses an IPCUtils class to create a connection to the AWS IoT Greengrass
Core IPC service. For more information, see Connect to the AWS IoT Greengrass Core IPC
service (p. 546).
package com.aws.greengrass.docs.samples.ipc;
import com.aws.greengrass.docs.samples.ipc.util.IPCUtils;
import software.amazon.awssdk.aws.greengrass.GetThingShadowResponseHandler;
import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient;
import software.amazon.awssdk.aws.greengrass.model.GetThingShadowRequest;
import software.amazon.awssdk.aws.greengrass.model.GetThingShadowResponse;
import software.amazon.awssdk.aws.greengrass.model.ResourceNotFoundError;
import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError;
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
import java.nio.charset.StandardCharsets;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
public class GetThingShadow {
public static final int TIMEOUT_SECONDS = 10;
public static void main(String[] args) {
// Use the current core device's name if thing name isn't set.
String thingName = args[0].isEmpty() ? System.getenv("AWS_IOT_THING_NAME") :
args[0];
String shadowName = args[1];
try (EventStreamRPCConnection eventStreamRPCConnection =
IPCUtils.getEventStreamRpcConnection()) {
GreengrassCoreIPCClient ipcClient =
new GreengrassCoreIPCClient(eventStreamRPCConnection);
GetThingShadowResponseHandler responseHandler =
GetThingShadow.getThingShadow(ipcClient, thingName, shadowName);
CompletableFuture<GetThingShadowResponse> futureResponse =
responseHandler.getResponse();
try {
GetThingShadowResponse response = futureResponse.get(TIMEOUT_SECONDS,
TimeUnit.SECONDS);
String shadowPayload = new String(response.getPayload(),
StandardCharsets.UTF_8);
System.out.printf("Successfully got shadow %s/%s: %s%n", thingName,
shadowName,
shadowPayload);
} catch (TimeoutException e) {
System.err.printf("Timeout occurred while getting shadow: %s/%s%n",
thingName,
624
AWS IoT Greengrass Developer Guide, Version 2
GetThingShadow
shadowName);
} catch (ExecutionException e) {
if (e.getCause() instanceof UnauthorizedError) {
System.err.printf("Unauthorized error while getting shadow: %s/%s
%n",
thingName, shadowName);
} else if (e.getCause() instanceof ResourceNotFoundError) {
System.err.printf("Unable to find shadow to get: %s/%s%n",
thingName,
shadowName);
} else {
throw e;
}
}
} catch (InterruptedException e) {
System.out.println("IPC interrupted.");
} catch (ExecutionException e) {
System.err.println("Exception occurred when using IPC.");
e.printStackTrace();
System.exit(1);
}
}
public static GetThingShadowResponseHandler getThingShadow(GreengrassCoreIPCClient
greengrassCoreIPCClient, String thingName, String shadowName) {
GetThingShadowRequest getThingShadowRequest = new GetThingShadowRequest();
getThingShadowRequest.setThingName(thingName);
getThingShadowRequest.setShadowName(shadowName);
return greengrassCoreIPCClient.getThingShadow(getThingShadowRequest,
Optional.empty());
}
}
Python
Example Example: Get a thing shadow
import awsiot.greengrasscoreipc
import awsiot.greengrasscoreipc.client as client
from awsiot.greengrasscoreipc.model import GetThingShadowRequest
TIMEOUT = 10
def sample_get_thing_shadow_request(thingName, shadowName):
try:
# set up IPC client to connect to the IPC server
ipc_client = awsiot.greengrasscoreipc.connect()
# create the GetThingShadow request
get_thing_shadow_request = GetThingShadowRequest()
get_thing_shadow_request.thing_name = thingName
get_thing_shadow_request.shadow_name = shadowName
# retrieve the GetThingShadow response after sending the request to the IPC
server
op = ipc_client.new_get_thing_shadow()
op.activate(get_thing_shadow_request)
fut = op.get_response()
result = fut.result(TIMEOUT)
return result.payload
except InvalidArgumentsError as e:
# add error handling
625
AWS IoT Greengrass Developer Guide, Version 2
UpdateThingShadow
...
# except ResourceNotFoundError | UnauthorizedError | ServiceError
UpdateThingShadow
Update the shadow for the specified thing.
Request
This operation's request has the following parameters:
thingName (Python: thing_name)
The name of the thing.
Type: string
shadowName (Python: shadow_name)
The name of the shadow. To specify the thing's classic shadow, set this parameter to an empty string
("").
Warning
The AWS IoT Greengrass service uses the AWSManagedGreengrassV2Deployment named
shadow to manage deployments that target individual core devices. This named shadow
is reserved for use by the AWS IoT Greengrass service. Do not update or delete this named
shadow.
Type: string
payload
The request state document as a blob.
Type: object that contains the following information:
state
The state information to update. This IPC operation affects only the specified fields.
This object contains the following information. Typically, you'll use either the desired property
or the reported property, but not both in the same request.
desired
The state properties and values requested to be updated in the device.
Type: map of key-value pairs
reported
The state properties and values reported by the device.
Type: map of key-value pairs
clientToken (Python: client_token)
(Optional) The token that is used to match the request and corresponding response by the client
token.
Type: string
626
AWS IoT Greengrass Developer Guide, Version 2
UpdateThingShadow
version
(Optional) The version of the local shadow document to update. The shadow service processes
the update only if the specified version matches the latest version that it has.
Type: integer
Response
This operation's response has the following information:
payload
The response state document as a blob.
Type: object that contains the following information:
state
The state information.
This object contains the following information.
desired
The state properties and values requested to be updated in the device.
Type: map of key-value pairs
reported
The state properties and values reported by the device.
Type: map of key-value pairs
delta
The state properties and values reported by the device.
Type: map of key-value pairs
metadata
The timestamps for each attribute in the desired and reported sections so that you can
determine when the state was updated.
Type: string
timestamp
The epoch date and time that the response was generated.
Type: integer
clientToken (Python: client_token)
The token that is used to match the request and corresponding response.
Type: string
version
The version of local shadow document after the update is complete.
627
AWS IoT Greengrass Developer Guide, Version 2
UpdateThingShadow
Type: integer
Errors
This operation can return the following errors.
ConflictError
The local shadow service encountered a version conflict during the update operation. This occurs
when the version in the request payload doesn't match the version in the latest available local
shadow document.
InvalidArgumentsError
The local shadow service is unable to validate the request parameters. This can occur if the request
contains malformed JSON or unsupported characters.
A valid payload has the following properties:
• The state node exists, and is an object that contains the desired or reported state
information.
• The desired and reported nodes are either objects or null. At least one of these objects must
contain valid state information.
• The depth of the desired and reported objects can't exceed eight nodes.
• The length of the clientToken value can't exceed 64 characters.
• The version value must be 1 or higher.
ServiceError
An internal service error occurred, or the number of requests to the IPC service exceeded the limits
specified in the maxLocalRequestsPerSecondPerThing and maxTotalLocalRequestsRate
configuration parameters in the shadow manager component.
UnauthorizedError
The component's authorization policy doesn't include required permissions for this operation.
Examples
The following examples demonstrate how to call this operation in custom component code.
Java
Example Example: Update a thing shadow
Note
This example uses an IPCUtils class to create a connection to the AWS IoT Greengrass
Core IPC service. For more information, see Connect to the AWS IoT Greengrass Core IPC
service (p. 546).
package com.aws.greengrass.docs.samples.ipc;
import com.aws.greengrass.docs.samples.ipc.util.IPCUtils;
import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient;
import software.amazon.awssdk.aws.greengrass.UpdateThingShadowResponseHandler;
import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError;
import software.amazon.awssdk.aws.greengrass.model.UpdateThingShadowRequest;
import software.amazon.awssdk.aws.greengrass.model.UpdateThingShadowResponse;
628
AWS IoT Greengrass Developer Guide, Version 2
UpdateThingShadow
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
import java.nio.charset.StandardCharsets;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
public class UpdateThingShadow {
public static final int TIMEOUT_SECONDS = 10;
public static void main(String[] args) {
// Use the current core device's name if thing name isn't set.
String thingName = args[0].isEmpty() ? System.getenv("AWS_IOT_THING_NAME") :
args[0];
String shadowName = args[1];
byte[] shadowPayload = args[2].getBytes(StandardCharsets.UTF_8);
try (EventStreamRPCConnection eventStreamRPCConnection =
IPCUtils.getEventStreamRpcConnection()) {
GreengrassCoreIPCClient ipcClient =
new GreengrassCoreIPCClient(eventStreamRPCConnection);
UpdateThingShadowResponseHandler responseHandler =
UpdateThingShadow.updateThingShadow(ipcClient, thingName,
shadowName,
shadowPayload);
CompletableFuture<UpdateThingShadowResponse> futureResponse =
responseHandler.getResponse();
try {
futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS);
System.out.printf("Successfully updated shadow: %s/%s%n", thingName,
shadowName);
} catch (TimeoutException e) {
System.err.printf("Timeout occurred while updating shadow: %s/%s%n",
thingName,
shadowName);
} catch (ExecutionException e) {
if (e.getCause() instanceof UnauthorizedError) {
System.err.printf("Unauthorized error while updating shadow: %s/%s
%n",
thingName, shadowName);
} else {
throw e;
}
}
} catch (InterruptedException e) {
System.out.println("IPC interrupted.");
} catch (ExecutionException e) {
System.err.println("Exception occurred when using IPC.");
e.printStackTrace();
System.exit(1);
}
}
public static UpdateThingShadowResponseHandler
updateThingShadow(GreengrassCoreIPCClient greengrassCoreIPCClient, String thingName,
String shadowName, byte[] shadowPayload) {
UpdateThingShadowRequest updateThingShadowRequest = new
UpdateThingShadowRequest();
updateThingShadowRequest.setThingName(thingName);
updateThingShadowRequest.setShadowName(shadowName);
updateThingShadowRequest.setPayload(shadowPayload);
return greengrassCoreIPCClient.updateThingShadow(updateThingShadowRequest,
Optional.empty());
}
629
AWS IoT Greengrass Developer Guide, Version 2
DeleteThingShadow
Python
Example Example: Update a thing shadow
import awsiot.greengrasscoreipc
import awsiot.greengrasscoreipc.client as client
from awsiot.greengrasscoreipc.model import UpdateThingShadowRequest
TIMEOUT = 10
def sample_update_thing_shadow_request(thingName, shadowName, payload):
try:
# set up IPC client to connect to the IPC server
ipc_client = awsiot.greengrasscoreipc.connect()
# create the UpdateThingShadow request
update_thing_shadow_request = UpdateThingShadowRequest()
update_thing_shadow_request.thing_name = thingName
update_thing_shadow_request.shadow_name = shadowName
update_thing_shadow_request.payload = payload
# retrieve the UpdateThingShadow response after sending the request to the IPC
server
op = ipc_client.new_update_thing_shadow()
op.activate(update_thing_shadow_request)
fut = op.get_response()
result = fut.result(TIMEOUT)
return result.payload
except InvalidArgumentsError as e:
# add error handling
...
# except ConflictError | UnauthorizedError | ServiceError
DeleteThingShadow
Deletes the shadow for the specified thing.
Beginning in shadow manager v2.0.4, deleting a shadow increments the version number. For example,
when you delete the shadow MyThingShadow at version 1, the version of the deleted shadow is 2. If you
then recreate a shadow with the name MyThingShadow, the version for that shadow is 3.
Request
This operation's request has the following parameters:
thingName (Python: thing_name)
The name of the thing.
Type: string
shadowName (Python: shadow_name)
The name of the shadow. To specify the thing's classic shadow, set this parameter to an empty string
("").
630
AWS IoT Greengrass Developer Guide, Version 2
DeleteThingShadow
Warning
The AWS IoT Greengrass service uses the AWSManagedGreengrassV2Deployment named
shadow to manage deployments that target individual core devices. This named shadow
is reserved for use by the AWS IoT Greengrass service. Do not update or delete this named
shadow.
Type: string
Response
This operation's response has the following information:
payload
An empty response state document.
Errors
This operation can return the following errors.
InvalidArgumentsError
The local shadow service is unable to validate the request parameters. This can occur if the request
contains malformed JSON or unsupported characters.
ResourceNotFoundError
The requested local shadow document can't be found.
ServiceError
An internal service error occurred, or the number of requests to the IPC service exceeded the limits
specified in the maxLocalRequestsPerSecondPerThing and maxTotalLocalRequestsRate
configuration parameters in the shadow manager component.
UnauthorizedError
The component's authorization policy doesn't include required permissions for this operation.
Examples
The following examples demonstrate how to call this operation in custom component code.
Java
Example Example: Delete a thing shadow
Note
This example uses an IPCUtils class to create a connection to the AWS IoT Greengrass
Core IPC service. For more information, see Connect to the AWS IoT Greengrass Core IPC
service (p. 546).
package com.aws.greengrass.docs.samples.ipc;
import com.aws.greengrass.docs.samples.ipc.util.IPCUtils;
import software.amazon.awssdk.aws.greengrass.DeleteThingShadowResponseHandler;
import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient;
import software.amazon.awssdk.aws.greengrass.model.DeleteThingShadowRequest;
631
AWS IoT Greengrass Developer Guide, Version 2
DeleteThingShadow
import software.amazon.awssdk.aws.greengrass.model.DeleteThingShadowResponse;
import software.amazon.awssdk.aws.greengrass.model.ResourceNotFoundError;
import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError;
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
public class DeleteThingShadow {
public static final int TIMEOUT_SECONDS = 10;
public static void main(String[] args) {
// Use the current core device's name if thing name isn't set.
String thingName = args[0].isEmpty() ? System.getenv("AWS_IOT_THING_NAME") :
args[0];
String shadowName = args[1];
try (EventStreamRPCConnection eventStreamRPCConnection =
IPCUtils.getEventStreamRpcConnection()) {
GreengrassCoreIPCClient ipcClient =
new GreengrassCoreIPCClient(eventStreamRPCConnection);
DeleteThingShadowResponseHandler responseHandler =
DeleteThingShadow.deleteThingShadow(ipcClient, thingName,
shadowName);
CompletableFuture<DeleteThingShadowResponse> futureResponse =
responseHandler.getResponse();
try {
futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS);
System.out.printf("Successfully deleted shadow: %s/%s%n", thingName,
shadowName);
} catch (TimeoutException e) {
System.err.printf("Timeout occurred while deleting shadow: %s/%s%n",
thingName,
shadowName);
} catch (ExecutionException e) {
if (e.getCause() instanceof UnauthorizedError) {
System.err.printf("Unauthorized error while deleting shadow: %s/%s
%n",
thingName, shadowName);
} else if (e.getCause() instanceof ResourceNotFoundError) {
System.err.printf("Unable to find shadow to delete: %s/%s%n",
thingName,
shadowName);
} else {
throw e;
}
}
} catch (InterruptedException e) {
System.out.println("IPC interrupted.");
} catch (ExecutionException e) {
System.err.println("Exception occurred when using IPC.");
e.printStackTrace();
System.exit(1);
}
}
public static DeleteThingShadowResponseHandler
deleteThingShadow(GreengrassCoreIPCClient greengrassCoreIPCClient, String thingName,
String shadowName) {
DeleteThingShadowRequest deleteThingShadowRequest = new
DeleteThingShadowRequest();
deleteThingShadowRequest.setThingName(thingName);
deleteThingShadowRequest.setShadowName(shadowName);
632
AWS IoT Greengrass Developer Guide, Version 2
ListNamedShadowsForThing
return greengrassCoreIPCClient.deleteThingShadow(deleteThingShadowRequest,
Optional.empty());
}
}
Python
Example Example: Delete a thing shadow
import awsiot.greengrasscoreipc
import awsiot.greengrasscoreipc.client as client
from awsiot.greengrasscoreipc.model import DeleteThingShadowRequest
TIMEOUT = 10
def sample_delete_thing_shadow_request(thingName, shadowName):
try:
# set up IPC client to connect to the IPC server
ipc_client = awsiot.greengrasscoreipc.connect()
# create the DeleteThingShadow request
delete_thing_shadow_request = DeleteThingShadowRequest()
delete_thing_shadow_request.thing_name = thingName
delete_thing_shadow_request.shadow_name = shadowName
# retrieve the DeleteThingShadow response after sending the request to the IPC
server
op = ipc_client.new_delete_thing_shadow()
op.activate(delete_thing_shadow_request)
fut = op.get_response()
result = fut.result(TIMEOUT)
return result.payload
except InvalidArgumentsError as e:
# add error handling
...
# except ResourceNotFoundError | UnauthorizedError | ServiceError
ListNamedShadowsForThing
List the named shadows for the specified thing.
Request
This operation's request has the following parameters:
thingName (Python: thing_name)
The name of the thing.
Type: string
pageSize (Python: page_size)
(Optional) The number of shadow names to return in each call.
Type: integer
Default: 25
633
AWS IoT Greengrass Developer Guide, Version 2
ListNamedShadowsForThing
Maximum: 100
nextToken (Python: next_token)
(Optional) The token to retrieve the next set of results. This value is returned on paged results and is
used in the call that returns the next page.
Type: string
Response
This operation's response has the following information:
results
The list of shadow names.
Type: array
timestamp
(Optional) The date and time that the response was generated.
Type: integer
nextToken (Python: next_token)
(Optional) The token value to use in paged requests to retrieve the next page in the sequence. This
token isn't present when there are no more shadow names to return.
Type: string
Note
If the requested page size exactly matches the number of shadow names in the response,
then this token is present; however, when used, it returns an empty list.
Errors
This operation can return the following errors.
InvalidArgumentsError
The local shadow service is unable to validate the request parameters. This can occur if the request
contains malformed JSON or unsupported characters.
ResourceNotFoundError
The requested local shadow document can't be found.
ServiceError
An internal service error occurred, or the number of requests to the IPC service exceeded the limits
specified in the maxLocalRequestsPerSecondPerThing and maxTotalLocalRequestsRate
configuration parameters in the shadow manager component.
UnauthorizedError
The component's authorization policy doesn't include required permissions for this operation.
Examples
The following examples demonstrate how to call this operation in custom component code.
634
AWS IoT Greengrass Developer Guide, Version 2
ListNamedShadowsForThing
Java
Example Example: List a thing's named shadows
Note
This example uses an IPCUtils class to create a connection to the AWS IoT Greengrass
Core IPC service. For more information, see Connect to the AWS IoT Greengrass Core IPC
service (p. 546).
package com.aws.greengrass.docs.samples.ipc;
import com.aws.greengrass.docs.samples.ipc.util.IPCUtils;
import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient;
import software.amazon.awssdk.aws.greengrass.ListNamedShadowsForThingResponseHandler;
import software.amazon.awssdk.aws.greengrass.model.ListNamedShadowsForThingRequest;
import software.amazon.awssdk.aws.greengrass.model.ListNamedShadowsForThingResponse;
import software.amazon.awssdk.aws.greengrass.model.ResourceNotFoundError;
import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError;
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
import java.util.ArrayList;
import java.util.List;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
public class ListNamedShadowsForThing {
public static final int TIMEOUT_SECONDS = 10;
public static void main(String[] args) {
// Use the current core device's name if thing name isn't set.
String thingName = args[0].isEmpty() ? System.getenv("AWS_IOT_THING_NAME") :
args[0];
try (EventStreamRPCConnection eventStreamRPCConnection =
IPCUtils.getEventStreamRpcConnection()) {
GreengrassCoreIPCClient ipcClient =
new GreengrassCoreIPCClient(eventStreamRPCConnection);
List<String> namedShadows = new ArrayList<>();
String nextToken = null;
try {
// Send additional requests until there's no pagination token in the
response.
do {
ListNamedShadowsForThingResponseHandler responseHandler =
ListNamedShadowsForThing.listNamedShadowsForThing(ipcClient, thingName,
nextToken, 25);
CompletableFuture<ListNamedShadowsForThingResponse> futureResponse
=
responseHandler.getResponse();
ListNamedShadowsForThingResponse response =
futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS);
List<String> responseNamedShadows = response.getResults();
namedShadows.addAll(responseNamedShadows);
nextToken = response.getNextToken();
} while (nextToken != null);
System.out.printf("Successfully got named shadows for thing %s: %s%n",
thingName,
String.join(",", namedShadows));
} catch (TimeoutException e) {
System.err.println("Timeout occurred while listing named shadows for
thing: " + thingName);
635
AWS IoT Greengrass Developer Guide, Version 2
ListNamedShadowsForThing
} catch (ExecutionException e) {
if (e.getCause() instanceof UnauthorizedError) {
System.err.println("Unauthorized error while listing named shadows
for " +
"thing: " + thingName);
} else if (e.getCause() instanceof ResourceNotFoundError) {
System.err.println("Unable to find thing to list named shadows: " +
thingName);
} else {
throw e;
}
}
} catch (InterruptedException e) {
System.out.println("IPC interrupted.");
} catch (ExecutionException e) {
System.err.println("Exception occurred when using IPC.");
e.printStackTrace();
System.exit(1);
}
}
public static ListNamedShadowsForThingResponseHandler
listNamedShadowsForThing(GreengrassCoreIPCClient greengrassCoreIPCClient, String
thingName, String nextToken, int pageSize) {
ListNamedShadowsForThingRequest listNamedShadowsForThingRequest =
new ListNamedShadowsForThingRequest();
listNamedShadowsForThingRequest.setThingName(thingName);
listNamedShadowsForThingRequest.setNextToken(nextToken);
listNamedShadowsForThingRequest.setPageSize(pageSize);
return
greengrassCoreIPCClient.listNamedShadowsForThing(listNamedShadowsForThingRequest,
Optional.empty());
}
}
Python
Example Example: List a thing's named shadows
import awsiot.greengrasscoreipc
import awsiot.greengrasscoreipc.client as client
from awsiot.greengrasscoreipc.model import ListNamedShadowsForThingRequest
TIMEOUT = 10
def sample_list_named_shadows_for_thing_request(thingName, nextToken, pageSize):
try:
# set up IPC client to connect to the IPC server
ipc_client = awsiot.greengrasscoreipc.connect()
# create the ListNamedShadowsForThingRequest request
list_named_shadows_for_thing_request = ListNamedShadowsForThingRequest()
list_named_shadows_for_thing_request.thing_name = thingName
list_named_shadows_for_thing_request.next_token = nextToken
list_named_shadows_for_thing_request.page_size = pageSize
# retrieve the ListNamedShadowsForThingRequest response after sending the
request to the IPC server
op = ipc_client.new_list_named_shadows_for_thing()
op.activate(list_named_shadows_for_thing_request)
fut = op.get_response()
list_result = fut.result(TIMEOUT)
636
AWS IoT Greengrass Developer Guide, Version 2
ListNamedShadowsForThing
# additional returned fields
timestamp = list_result.timestamp
next_token = result.next_token
named_shadow_list = list_result.results
return named_shadow_list, next_token, timestamp
except InvalidArgumentsError as e:
# add error handling
...
# except ResourceNotFoundError | UnauthorizedError | ServiceError
637
AWS IoT Greengrass Developer Guide, Version 2
Tutorial: Connect and test client devices
Interact with local IoT devices
Client devices are local IoT devices that connect to and communicate with a Greengrass core device over
MQTT. You can connect client devices to core devices to do the following:
• Relay messages and data between client devices and AWS IoT Core.
• Interact with MQTT messages in Greengrass components.
To connect to a core device, client devices can use cloud discovery. Client devices connect to the AWS IoT
Greengrass cloud service to retrieve information about core devices to which they can connect. Then,
they can connect to a core device to process their messages and sync their data with the AWS IoT Core
cloud service.
You can follow a tutorial that walks through how to configure a core device to connect and communicate
with an AWS IoT thing. This tutorial also explores how to develop a custom Greengrass component
that interacts with client devices. For more information, see Tutorial: Connect and test client
devices (p. 638).
Topics
• Tutorial: Connect and test client devices (p. 638)
• AWS-provided client device components (p. 650)
• Connect client devices to core devices (p. 643)
• Relay MQTT messages between client devices and AWS IoT Core (p. 668)
• Interact with client devices in components (p. 670)
• Troubleshooting client devices (p. 672)
Tutorial: Connect and test client devices
You can complete this tutorial to configure a core device to interact with local IoT devices, called client
devices, that connect to the core device over MQTT. In this tutorial, you configure AWS IoT things to
use cloud discovery to connect to the core device as client devices. When you configure cloud discovery,
a client device can send a request to the AWS IoT Greengrass cloud service to discover core devices.
The response from AWS IoT Greengrass includes connectivity information and certificates for the core
devices that you configure the client device to discover. Then, the client device can use this information
to connect to an available core device where it can communicate over MQTT.
In this tutorial, you do the following:
• Review and update the core device's permissions, if needed.
• Associate client devices to the core device, so they can discover the core device using cloud discovery.
• Deploy Greengrass components to the core device to enable client device support.
• Connect client devices to the core device and test communication with the AWS IoT Core cloud service.
• Develop a custom Greengrass component that interacts with the client devices.
This tutorial uses a single core device and a single client device. You can also follow the tutorial to
connect and test multiple client devices.
You can expect to spend 30–50 minutes on this tutorial.
638
AWS IoT Greengrass Developer Guide, Version 2
Prerequisites
Prerequisites
To complete this tutorial, you must meet the following prerequisites:
• An AWS account. If you don't have one, see Set up an AWS account (p. 66).
• An AWS Identity and Access Management (IAM) user with administrator permissions.
• A Greengrass core device. For more information about how to set up a core device, see Setting up AWS
IoT Greengrass core devices (p. 62).
• The core device must be on the same network as the client devices to connect.
• (Optional) To complete the module where you develop a custom component that interacts with
client devices, the core device must run the Greengrass CLI. For more information, see Install the
Greengrass CLI (p. 428).
• An AWS IoT thing to connect as a client device in this tutorial. For more information, see Create AWS
IoT resources in the AWS IoT Core Developer Guide.
• The client device's AWS IoT policy must allow the greengrass:Discover permission. For more
information, see Minimal AWS IoT policy for client devices (p. 780).
• The client device must be on the same network as the core device.
• The client device must run Python 3.
• The client device must run Git.
Review and update the core device AWS IoT policy
To support client devices, a core device's AWS IoT policy must allow the following permissions:
• greengrass:PutCertificateAuthorities
• greengrass:VerifyClientDeviceIdentity
• greengrass:VerifyClientDeviceIoTCertificateAssociation
• greengrass:GetConnectivityInfo
• greengrass:UpdateConnectivityInfo – (Optional) This permission is required to use the IP
detector component (p. 240), which reports the core device's network connectivity information to the
AWS IoT Greengrass cloud service.
For more information, see AWS IoT policies for data plane operations (p. 774) and Minimal AWS IoT
policy to support client devices (p. 779).
In this section, you review the AWS IoT policies for your core device and add any required
permissions that are missing. If you used the AWS IoT Greengrass Core software installer to provision
resources (p. 69), your core device has an AWS IoT policy that allows access to all AWS IoT Greengrass
actions (greengrass:*).
To review and update a core device's AWS IoT policy
1. In the AWS IoT Greengrass console navigation menu, choose Core devices.
2. On the Core devices page, choose the core device to update.
3. On the core device details page, choose the link to the core device's Thing. This link opens the thing
details page in the AWS IoT console.
4. On the thing details page, choose Certificates.
5. In the Certificates tab, choose the thing's active certificate.
6. On the certificate details page, choose Policies.
7. In the Policies tab, choose the AWS IoT policy to review and update. You can add the required
permissions to any policy that is attached to the core device's active certificate.
639
AWS IoT Greengrass Developer Guide, Version 2
Enable client device support
Note
If you used the AWS IoT Greengrass Core software installer to provision resources (p. 69),
you have two AWS IoT policies. We recommend that you choose the policy named
GreengrassV2IoTThingPolicy, if it exists. Core devices that you create with the quick
installer use this policy name by default. If you add permissions to this policy, you are also
granting these permissions to other core devices that use this policy.
8. In the policy overview, choose Edit policy document.
9. Review the policy for the required permissions, and add any required permissions that are missing.
10. Choose Save as new version.
Enable client device support
For a client device to use cloud discovery to connect to a core device, you must associate the devices.
When you associate a client device to a core device, you enable that client device to retrieve the core
device's IP addresses and certificates to use to connect.
To enable client devices to securely connect to a core device and communicate with Greengrass
components and AWS IoT Core, you deploy the following Greengrass components to the core device:
• Client device auth (p. 194) (aws.greengrass.clientdevices.Auth)
Deploy the client device auth component to authenticate client devices and authorize client device
actions. This component allows your AWS IoT things to connect to a core device.
This component requires some configuration to use it. You must specify groups of client devices and
the operations that each group is authorized to perform, such as to connect and communicate over
MQTT. For more information, see client device auth component configuration (p. 197).
• MQTT broker (Moquette) (p. 365) (aws.greengrass.clientdevices.mqtt.Moquette)
Deploy the Moquette MQTT broker component to run the open source Moquette MQTT broker. The
Moquette MQTT broker is compliant with MQTT 3.1.1 and includes local support for QoS 0, QoS 1,
QoS 2, retained messages, last will messages, and persistent subscriptions.
You aren't required to configure this component to use it. However, you can configure the port where
this component operates the MQTT broker. By default, it uses port 8883.
• MQTT bridge (p. 360) (aws.greengrass.clientdevices.mqtt.Bridge)
(Optional) Deploy the MQTT bridge component to relay messages between client devices (local MQTT),
local publish/subscribe, and AWS IoT Core MQTT. Configure this component to sync client devices with
AWS IoT Core and interact with client devices from Greengrass components.
This component requires configuration to use. You must specify the topic mappings where
this component relays messages. For more information, see MQTT bridge component
configuration (p. 361).
• IP detector (p. 240) (aws.greengrass.clientdevices.IPDetector)
(Optional) Deploy the IP detector component to automatically report the core device's MQTT broker
endpoints to the AWS IoT Greengrass cloud service. You cannot use this component if you have a
complex network setup, such as one where a router forwards the MQTT broker port to the core device.
You aren't required to configure this component to use it.
In this section, you use the AWS IoT Greengrass console to associate client devices and deploy client
device components to a core device.
640
AWS IoT Greengrass Developer Guide, Version 2
Enable client device support
To enable client device support
1. Navigate to the AWS IoT Greengrass console.
2. In the left navigation menu, choose Core devices.
3. On the Core devices page, choose the core device where you want to enable client device support.
4. On the core device details page, choose the Client devices tab.
5. On the Client devices tab, choose Configure cloud discovery.
The Configure core device discovery page opens. On this page, you can associate client devices to a
core device and deploy client device components. This page selects the core device for you in Step 1:
Select target core devices.
Note
You can also use this page to configure core device discovery for a thing group. If you
choose this option, you can deploy client device components to all core devices in a thing
group. However, if you choose this option, you must manually associate client devices to
each core device later after you create the deployment. In this tutorial, you configure a
single core device.
6. In Step 2: Associate client devices, associate the client device's AWS IoT thing to the core device.
This enables the client device to use cloud discovery to retrieve the core device's connectivity
information and certificates. Do the following:
a. Choose Associate client devices.
b. In the Associate client devices with core device modal, enter the name of the AWS IoT thing to
associate.
c. Choose Add.
d. Choose Associate.
7. In Step 3: Configure and deploy Greengrass components, deploy components to enable client
device support. If the target core device has a previous deployment, this page revises that
deployment. Otherwise, this page creates a new deployment for the core device. Do the following to
configure and deploy the client device components:
a. The core device must run Greengrass nucleus (p. 181) v2.2.0 or later to support client devices.
If the core device runs an earlier version, select the box to deploy the aws.greengrass.Nucleus
component.
Note
If you upgrade the Greengrass nucleus from an earlier minor version, and the core
device runs public components (p. 175) that depend on the nucleus, you must also
update the public components to newer versions. You can configure the version of
these components when you review the deployment later in this tutorial. For more
information, see Update the AWS IoT Greengrass Core software (OTA) (p. 170).
b. For the aws.greengrass.clientdevices.Auth component, choose Edit configuration.
c. In the Edit configuration modal for the client device auth component, configure an
authorization policy that allows client devices to publish and subscribe to the MQTT broker on
the core device. Do the following:
i. Under Configuration, in the Configuration to merge code block, enter the following
configuration, which contains a device group authorization policy. Each device group
authorization policy specifies a set of actions and the resources on which a client device can
perform those actions.
• This policy allows client devices whose names start with MyClientDevice to connect
and communicate on all MQTT topics. Replace MyClientDevice* with the name of
the AWS IoT thing to connect as a client device. You can also specify a name with the *
641
AWS IoT Greengrass Developer Guide, Version 2
Enable client device support
wildcard that matches the client device's name. The * wildcard must be at the end of the
name.
If you have a second client device to connect, replace MyOtherClientDevice* with the
name of that client device, or a wildcard pattern that matches that client device's name.
Otherwise, you can remove or keep this section of the selection rule that allows client
devices with names that match MyOtherClientDevice* to connect and communicate.
• This policy uses an OR operator to also allow client devices whose names start with
MyOtherClientDevice to connect and communicate on all MQTT topics. You can
remove this clause in the selection rule or modify it to match the client devices to
connect.
• This policy allows the client devices to publish and subscribe on all MQTT topics. To
follow best security practices, restrict the mqtt:publish and mqtt:subscribe
operations to the minimal set of topics that the client devices use to communicate.
{
"deviceGroups": {
"formatVersion": "2021-03-05",
"definitions": {
"MyDeviceGroup": {
"selectionRule": "thingName: MyClientDevice* OR
thingName: MyOtherClientDevice*",
"policyName": "MyClientDevicePolicy"
}
},
"policies": {
"MyClientDevicePolicy": {
"AllowConnect": {
"statementDescription": "Allow client devices to connect.",
"operations": [
"mqtt:connect"
],
"resources": [
"*"
]
},
"AllowPublish": {
"statementDescription": "Allow client devices to publish to all
topics.",
"operations": [
"mqtt:publish"
],
"resources": [
"*"
]
},
"AllowSubscribe": {
"statementDescription": "Allow client devices to subscribe to all
topics.",
"operations": [
"mqtt:subscribe"
],
"resources": [
"*"
]
}
}
}
}
}
642
AWS IoT Greengrass Developer Guide, Version 2
Connect client devices
For more information, see Client device auth component configuration (p. 197).
ii. Choose Confirm.
d. For the aws.greengrass.clientdevices.mqtt.Bridge component, choose Edit configuration.
e. In the Edit configuration modal for the MQTT bridge component, configure a topic mapping
that relays MQTT messages from client devices to AWS IoT Core. Do the following:
i. Under Configuration, in the Configuration to merge code block, enter the following
configuration. This configuration specifies to relay MQTT messages on the clients/
+/hello/world topic filter from client devices to the AWS IoT Core cloud service. For
example, this topic filter matches the clients/MyClientDevice1/hello/world topic.
{
"mqttTopicMapping": {
"HelloWorldIotCoreMapping": {
"topic": "clients/+/hello/world",
"source": "LocalMqtt",
"target": "IotCore"
}
}
}
For more information, see MQTT bridge component configuration (p. 361).
ii. Choose Confirm.
8. Choose Review and deploy to review the deployment that this page creates for you.
9. If you haven't previously set up the Greengrass service role (p. 796) in this Region, the console
opens a modal to set up the service role for you. The client device auth component uses this service
role to verify the identity of client devices, and the IP detector component uses this service role to
manage core device connectivity information. Choose Grant permissions.
10. On the Review page, choose Deploy to start the deployment to the core device.
11. To verify that the deployment succeeds, check the status of the deployment, and check the logs on
the core device. To check the status of the deployment on the core device, you can choose Target in
the deployment Overview. For more information, see the following:
• Check deployment status (p. 504)
• Monitor AWS IoT Greengrass logs (p. 506)
Connect client devices
Client devices can use the AWS IoT Device SDK to discover, connect, and communicate with a core device.
In this section, you install the AWS IoT Device SDK v2 for Python and run the Greengrass discovery
sample application from the AWS IoT Device SDK.
Note
The AWS IoT Device SDK is also available in other programming languages. This tutorial uses the
AWS IoT Device SDK v2 for Python, but you can explore the other SDKs for your use case. For
more information, see AWS IoT Device SDKs in the AWS IoT Core Developer Guide.
To connect a client device to a core device
1. Download and install the AWS IoT Device SDK v2 for Python to the AWS IoT thing to connect as a
client device.
On the client device, do the following:
a. Clone the AWS IoT Device SDK v2 for Python repository to download it.
643
AWS IoT Greengrass Developer Guide, Version 2
Connect client devices
git clone https://github.com/aws/aws-iot-device-sdk-python-v2.git
b. Install the AWS IoT Device SDK v2 for Python.
python3 -m pip install --user ./aws-iot-device-sdk-python-v2
2. Change to the samples folder in the AWS IoT Device SDK v2 for Python.
cd aws-iot-device-sdk-python-v2/samples
3. Run the sample Greengrass discovery application. This application expects arguments that specify
the client device thing name, the MQTT topic and message to use, and the certificates that
authenticate and secure the connection. The following example sends a Hello World message to the
clients/MyClientDevice1/hello/world topic.
Note
This topic is the same topic where you configured the MQTT bridge to relay messages to
AWS IoT Core earlier.
• Replace both instances of MyClientDevice1 with the client device's thing name.
• Replace ~/certs/AmazonRootCA1.pem with the path to the Amazon root CA certificate on the
client device.
• Replace ~/certs/device.pem.crt with the path to the device certificate on the client device.
• Replace ~/certs/private.pem.key with the path to the private key file on the client device.
• Replace us-east-1 with the AWS Region where your client device and core device operate.
python3 basic_discovery.py \
--thing-name MyClientDevice1 \
--topic 'clients/MyClientDevice1/hello/world' \
--message 'Hello World!' \
--root-ca ~/certs/AmazonRootCA1.pem \
--cert ~/certs/device.pem.crt \
--key ~/certs/private.pem.key \
--region us-east-1 \
--verbosity Warn
The discovery sample application sends the message 10 times and disconnects. It also subscribes
to the same topic where it publishes messages. If the output indicates that the application received
MQTT messages on the topic, the client device can successfully communicate with the core device.
Performing greengrass discovery...
awsiot.greengrass_discovery.DiscoverResponse(gg_groups=[awsiot.greengrass_discovery.GGGroup(gg_grou
coreDevice-MyGreengrassCore',
cores=[awsiot.greengrass_discovery.GGCore(thing_arn='arn:aws:iot:us-
east-1:123456789012:thing/MyGreengrassCore',
connectivity=[awsiot.greengrass_discovery.ConnectivityInfo(id='203.0.113.0',
host_address='203.0.113.0', metadata='', port=8883)])],
certificate_authorities=['-----BEGIN CERTIFICATE-----\nMIICiT...EXAMPLE=\n-----END
CERTIFICATE-----\n'])])
Trying core arn:aws:iot:us-east-1:123456789012:thing/MyGreengrassCore at host
203.0.113.0 port 8883
Connected!
Published topic clients/MyClientDevice1/hello/world: {"message": "Hello World!",
"sequence": 0}
Publish received on topic clients/MyClientDevice1/hello/world
b'{"message": "Hello World!", "sequence": 0}'
644
AWS IoT Greengrass Developer Guide, Version 2
Develop a component that interacts with client devices
Published topic clients/MyClientDevice1/hello/world: {"message": "Hello World!",
"sequence": 1}
Publish received on topic clients/MyClientDevice1/hello/world
b'{"message": "Hello World!", "sequence": 1}'
...
Published topic clients/MyClientDevice1/hello/world: {"message": "Hello World!",
"sequence": 9}
Publish received on topic clients/MyClientDevice1/hello/world
b'{"message": "Hello World!", "sequence": 9}'
If the application outputs an error instead, see Troubleshooting Greengrass discovery
issues (p. 672).
You can also view the Greengrass logs on the core device to verify if the client device successfully
connects and sends messages. For more information, see Monitor AWS IoT Greengrass logs (p. 506).
4. Verify that the MQTT bridge relays the messages from the client device to AWS IoT Core. You can
use the MQTT test client in the AWS IoT Core console to subscribe to an MQTT topic filter. Do the
following:
a. Navigate to the AWS IoT console.
b. In the left navigation menu, under Test, choose MQTT test client.
c. On the Subscribe to a topic tab, for Topic filter, enter clients/+/hello/world to subscribe
to client device messages from the core device.
d. Choose Subscribe.
e. Run the publish/subscribe application on the client device again.
The MQTT test client displays the messages that you send from the client device on topics that
match this topic filter.
Develop a component that interacts with client
devices
You can develop Greengrass components that interact with client devices. Components use interprocess
communication (IPC) (p. 545) and the local publish/subscribe interface (p. 561) to communicate on a
core device. To interact with client devices, configure the MQTT bridge component to relay messages
between client devices and local publish/subscribe.
In this section, you update the MQTT bridge component to relay messages from client devices to the
local publish/subscribe interface. Then, you develop a component that subscribes to these messages and
prints the messages when it receives them.
To develop a component that interacts with client devices
1. Revise the deployment to the core device and configure the MQTT bridge component to relay
messages from client devices to local publish/subscribe. Do the following:
a. Navigate to the AWS IoT Greengrass console.
b. In the left navigation menu, choose Core devices.
c. On the Core devices page, choose the core device that you are using for this tutorial.
d. On the core device details page, choose the Client devices tab.
e. On the Client devices tab, choose Configure cloud discovery.
645
AWS IoT Greengrass Developer Guide, Version 2
Develop a component that interacts with client devices
The Configure core device discovery page opens. On this page, you can change or configure
which client device components deploy to the core device.
f. In Step 3, for the aws.greengrass.clientdevices.mqtt.Bridge component, choose Edit
configuration.
g. In the Edit configuration modal for the MQTT bridge component, configure a topic mapping
that relays MQTT messages from client devices to the local publish/subscribe interface. Do the
following:
i. Under Configuration, in the Configuration to merge code block, enter the following
configuration. This configuration specifies to relay MQTT messages on topics that match
the clients/+/hello/world topic filter from client devices to the AWS IoT Core cloud
service and the local Greengrass publish/subscribe broker.
{
"mqttTopicMapping": {
"HelloWorldIotCoreMapping": {
"topic": "clients/+/hello/world",
"source": "LocalMqtt",
"target": "IotCore"
},
"HelloWorldPubsubMapping": {
"topic": "clients/+/hello/world",
"source": "LocalMqtt",
"target": "Pubsub"
}
}
}
For more information, see MQTT bridge component configuration (p. 361).
ii. Choose Confirm.
h. Choose Review and deploy to review the deployment that this page creates for you.
i. On the Review page, choose Deploy to start the deployment to the core device.
j. To verify that the deployment succeeds, check the status of the deployment, and check the logs
on the core device. To check the status of the deployment on the core device, you can choose
Target in the deployment Overview. For more information, see the following:
• Check deployment status (p. 504)
• Monitor AWS IoT Greengrass logs (p. 506)
2. Develop and deploy a Greengrass component that subscribes to Hello World messages from client
devices. For more information, see Create AWS IoT Greengrass components (p. 442).
a. Create a component recipe with the following contents. This recipe specifies installing the
AWS IoT Device SDK v2 for Python and running a script that subscribes to the topic and prints
messages.
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.clientdevices.MyHelloWorldSubscriber",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that subscribes to Hello World messages from
client devices.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"accessControl": {
"aws.greengrass.ipc.pubsub": {
"com.example.clientdevices.MyHelloWorldSubscriber:pubsub:1": {
646
AWS IoT Greengrass Developer Guide, Version 2
Develop a component that interacts with client devices
"policyDescription": "Allows access to subscribe to all topics.",
"operations": [
"aws.greengrass#SubscribeToTopic"
],
"resources": [
"*"
]
}
}
}
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"Install": "python3 -m pip install --user awsiotsdk",
"Run": "python3 -u {artifacts:path}/hello_world_subscriber.py"
}
},
{
"Platform": {
"os": "windows"
},
"Lifecycle": {
"Install": "py -3 -m pip install --user awsiotsdk",
"Run": "py -3 -u {artifacts:path}/hello_world_subscriber.py"
}
}
]
}
b. Create a Python script artifact named hello_world_subscriber.py with the following
contents. This application uses the publish/subscribe IPC service to subscribe to the
clients/MyClientDevice1/hello/world topic and print messages that it receives. Replace
MyClientDevice1 with the name of the client device.
import concurrent.futures
import sys
import time
import traceback
import awsiot.greengrasscoreipc
import awsiot.greengrasscoreipc.client as client
from awsiot.greengrasscoreipc.model import (
SubscribeToTopicRequest,
SubscriptionResponseMessage,
UnauthorizedError
)
topic = "clients/MyClientDevice1/hello/world"
TIMEOUT = 10
class StreamHandler(client.SubscribeToTopicStreamHandler):
def __init__(self):
super().__init__()
def on_stream_event(self, event: SubscriptionResponseMessage) -> None:
try:
message = str(event.binary_message.message, "utf-8")
print("Received new message: " + message)
647
AWS IoT Greengrass Developer Guide, Version 2
Develop a component that interacts with client devices
except:
traceback.print_exc()
def on_stream_error(self, error: Exception) -> bool:
print("Received a stream error.", file=sys.stderr)
traceback.print_exc()
return False # Return True to close stream, False to keep stream open.
def on_stream_closed(self) -> None:
print('Subscribe to topic stream closed.')
try:
ipc_client = awsiot.greengrasscoreipc.connect()
request = SubscribeToTopicRequest()
request.topic = topic
handler = StreamHandler()
operation = ipc_client.new_subscribe_to_topic(handler)
future = operation.activate(request)
try:
future.result(TIMEOUT)
print('Successfully subscribed to topic: ' + topic)
except concurrent.futures.TimeoutError as e:
print('Timeout occurred while subscribing to topic: ' + topic,
file=sys.stderr)
raise e
except UnauthorizedError as e:
print('Unauthorized error while subscribing to topic: ' + topic,
file=sys.stderr)
raise e
except Exception as e:
print('Exception while subscribing to topic: ' + topic, file=sys.stderr)
raise e
# Keep the main thread alive, or the process will exit.
try:
while True:
time.sleep(10)
except InterruptedError:
print('Subscribe interrupted.')
except Exception:
print('Exception occurred when using IPC.', file=sys.stderr)
traceback.print_exc()
exit(1)
c. Use the Greengrass CLI to deploy the component.
Linux or Unix
sudo /greengrass/v2/bin/greengrass-cli deployment create \
--recipeDir recipes \
--artifactDir artifacts \
--merge "com.example.clientdevices.MyHelloWorldSubscriber=1.0.0"
Windows Command Prompt (CMD)
C:\greengrass\v2/bin/greengrass-cli deployment create ^
--recipeDir recipes ^
--artifactDir artifacts ^
--merge "com.example.clientdevices.MyHelloWorldSubscriber=1.0.0"
648
AWS IoT Greengrass Developer Guide, Version 2
Develop a component that interacts with client devices
PowerShell
C:\greengrass\v2/bin/greengrass-cli deployment create `
--recipeDir recipes `
--artifactDir artifacts `
--merge "com.example.clientdevices.MyHelloWorldSubscriber=1.0.0"
3. View the component logs to verify that the component installs successfully and subscribes to the
topic.
Linux or Unix
sudo tail -f /greengrass/v2/logs/
com.example.clientdevices.MyHelloWorldSubscriber.log
PowerShell
gc C:\greengrass\v2/logs/com.example.clientdevices.MyHelloWorldSubscriber.log -Tail
10 -Wait
You can keep the log feed open to verify that the core device receives messages.
4. On the client device, run the sample Greengrass discovery application again to send messages to the
core device.
python3 basic_discovery.py \
--thing-name MyClientDevice1 \
--topic 'clients/MyClientDevice1/hello/world' \
--message 'Hello World!' \
--root-ca ~/certs/AmazonRootCA1.pem \
--cert ~/certs/device.pem.crt \
--key ~/certs/private.pem.key \
--region us-east-1 \
--verbosity Warn
5. View the component logs again to verify that the component receives and prints the messages from
the client device.
Linux or Unix
sudo tail -f /greengrass/v2/logs/
com.example.clientdevices.MyHelloWorldSubscriber.log
PowerShell
gc C:\greengrass\v2/logs/com.example.clientdevices.MyHelloWorldSubscriber.log -Tail
10 -Wait
You've completed this tutorial. The client device connects to the core device and sends MQTT messages
to AWS IoT Core and Greengrass components. For more information about the topics covered in this
tutorial, see the following:
• Associate client devices (p. 652)
• Manage core device endpoints (p. 654)
• Test client device communications (p. 657)
649
AWS IoT Greengrass Developer Guide, Version 2
Client device components
• Greengrass discovery RESTful API (p. 664)
• Relay MQTT messages between client devices and AWS IoT Core (p. 668)
• Interact with client devices in components (p. 670)
AWS-provided client device components
AWS IoT Greengrass provides the following public components that you can deploy to core devices.
These components enable client devices to connect and communicate with a core device.
Note
Several AWS-provided components depend on specific minor versions of the Greengrass
nucleus. Because of this dependency, you need to update these components when you update
the Greengrass nucleus to a new minor version. For information about the specific versions
of the nucleus that each component depends on, see the corresponding component topic.
For more information about updating the nucleus, see Update the AWS IoT Greengrass Core
software (OTA) (p. 170).
Component Description Depends Component Supported Open
on type (p. 441)OS source (p. 921)
nucleus
Client device auth (p. 194) Enables local Yes Plugin Linux, Yes
IoT devices, Windows
called client
devices, to
connect to
the core
device.
IP detector (p. 240) Reports Yes Plugin Linux, Yes
MQTT broker Windows
connectivity
information
to AWS IoT
Greengrass,
so client
devices can
discover how
to connect.
MQTT bridge (p. 360) Relays MQTT No Plugin Linux, Yes
messages Windows
between
client devices,
local AWS IoT
Greengrass
publish/
subscribe, and
AWS IoT Core.
MQTT broker (Moquette) (p. 365) Handles No Plugin Linux, Yes
MQTT Windows
messages
between
client devices
650
AWS IoT Greengrass Developer Guide, Version 2
Connect client devices to core devices
Component Description Depends Component Supported Open
on type (p. 441)OS source (p. 921)
nucleus
and the core
device.
Connect client devices to core devices
You can configure cloud discovery to connect client devices to core devices. When you configure cloud
discovery, client devices can connect to the AWS IoT Greengrass cloud service to retrieve information
about core devices to which they can connect. Then, the client devices can attempt to connect to each
core device until they successfully connect.
To use cloud discovery, you must do the following:
• Associate client devices to the core devices to which they can connect.
• Specify the MQTT broker endpoints where client devices can connect to each core device.
• Deploy components to the core device that enable support for client devices.
You can also deploy optional components to do the following:
• Relay messages between client devices, Greengrass components, and the AWS IoT Core cloud
service.
• Automatically manage core device MQTT broker endpoints for you.
You must also review and update the core device's AWS IoT policy to ensure that it has the permissions
required to connect client devices. For more information, see Review and update the core device AWS IoT
policy (p. 639).
After you configure cloud discovery, you can test communications between a client device and a core
device. For more information, see Test client device communications (p. 657).
Topics
• Greengrass components for client device support (p. 651)
• Configure cloud discovery (console) (p. 652)
• Configure cloud discovery (AWS CLI) (p. 652)
• Associate client devices (p. 652)
• Manage core device endpoints (p. 654)
• Test client device communications (p. 657)
• Greengrass discovery RESTful API (p. 664)
Greengrass components for client device support
To enable client devices to connect and communicate with a core device, you deploy the following
Greengrass components to the core device:
• Client device auth (p. 194) (aws.greengrass.clientdevices.Auth)
Deploy the client device auth component to authenticate client devices and authorize client device
actions. This component allows your AWS IoT things to connect to a core device.
651
AWS IoT Greengrass Developer Guide, Version 2
Configure cloud discovery (console)
This component requires some configuration to use it. You must specify groups of client devices and
the operations that each group is authorized to perform, such as to connect and communicate over
MQTT. For more information, see client device auth component configuration (p. 197).
• MQTT broker (Moquette) (p. 365) (aws.greengrass.clientdevices.mqtt.Moquette)
Deploy the Moquette MQTT broker component to run the open source Moquette MQTT broker. The
Moquette MQTT broker is compliant with MQTT 3.1.1 and includes local support for QoS 0, QoS 1,
QoS 2, retained messages, last will messages, and persistent subscriptions.
You aren't required to configure this component to use it. However, you can configure the port where
this component operates the MQTT broker. By default, it uses port 8883.
• MQTT bridge (p. 360) (aws.greengrass.clientdevices.mqtt.Bridge)
(Optional) Deploy the MQTT bridge component to relay messages between client devices (local MQTT),
local publish/subscribe, and AWS IoT Core MQTT. Configure this component to sync client devices with
AWS IoT Core and interact with client devices from Greengrass components.
This component requires configuration to use. You must specify the topic mappings where
this component relays messages. For more information, see MQTT bridge component
configuration (p. 361).
• IP detector (p. 240) (aws.greengrass.clientdevices.IPDetector)
(Optional) Deploy the IP detector component to automatically report the core device's MQTT broker
endpoints to the AWS IoT Greengrass cloud service. You cannot use this component if you have a
complex network setup, such as one where a router forwards the MQTT broker port to the core device.
You aren't required to configure this component to use it.
Important
The core device must run Greengrass nucleus (p. 181) v2.2.0 or later to support client devices.
Configure cloud discovery (console)
You can use the AWS IoT Greengrass console to associate client devices, manage core device endpoints,
and deploy components to enable client device support. For more information, see Enable client device
support (p. 640).
Configure cloud discovery (AWS CLI)
You can use the AWS Command Line Interface (AWS CLI) to associate client devices, manage core device
endpoints, and deploy components to enable client device support. For more information, see the
following:
• Manage client device associations (AWS CLI) (p. 654)
• Manage core device endpoints (p. 654)
• AWS-provided client device components (p. 650)
• Create deployments (p. 493)
Associate client devices
To use cloud discovery, associate client devices with a core device so that they can discover the core
device. Then, they can use the Greengrass discovery API (p. 664) to retrieve connectivity information
and certificates for their associated core devices.
652
AWS IoT Greengrass Developer Guide, Version 2
Associate client devices
Likewise, disassociate client devices from a core device to stop them from discovering the core device.
Topics
• Manage client device associations (console) (p. 653)
• Manage client device associations (AWS CLI) (p. 654)
• Manage client device associations (API) (p. 654)
Manage client device associations (console)
You can use the AWS IoT Greengrass console to view, add, and delete client device associations.
To view client device associations for a core device (console)
1. Navigate to the AWS IoT Greengrass console.
2. Choose Core devices.
3. Choose the core device to manage.
4. On the core device's details page, choose the Client devices tab.
5. In the Associated client devices section, you can see which client devices (AWS IoT things) are
associated with the core device.
To associate client devices with a core device (console)
1. Navigate to the AWS IoT Greengrass console.
2. Choose Core devices.
3. Choose the core device to manage.
4. On the core device's details page, choose the Client devices tab.
5. In the Associated client devices section, choose Associate client devices.
6. In the Associate client devices with core device modal, do the following for each client device to
associate:
a. Enter the name of the AWS IoT thing to associate as a client device.
b. Choose Add.
7. Choose Associate.
The client devices that you associated can now use the Greengrass discovery API to discover this core
device.
To disassociate client devices from a core device (console)
1. Navigate to the AWS IoT Greengrass console.
2. Choose Core devices.
3. Choose the core device to manage.
4. On the core device's details page, choose the Client devices tab.
5. In the Associated client devices section, select each client device to disassociate.
6. Choose Disassociate.
7. In the confirmation modal, choose Disassociate.
The client devices that you disassociated can no longer use the Greengrass discovery API to discover
this core device.
653
AWS IoT Greengrass Developer Guide, Version 2
Manage core device endpoints
Manage client device associations (AWS CLI)
You can use the AWS Command Line Interface (AWS CLI) to manage client device associations for a core
device.
To view client device associations for a core device (AWS CLI)
• Use the following command: list-client-devices-associated-with-core-device.
To associate client devices with a core device (AWS CLI)
• Use the following command: batch-associate-client-device-with-core-device.
To disassociate client devices from a core device (AWS CLI)
• Use the following command: batch-disassociate-client-device-from-core-device.
Manage client device associations (API)
You can use the AWS API to manage client device associations for a core device.
To view client device associations for a core device (AWS API)
• Use the following operation: ListClientDevicesAssociatedWithCoreDevice.
To associate client devices with a core device (AWS API)
• Use the following operation: BatchAssociateClientDeviceWithCoreDevice.
To disassociate client devices from a core device (AWS API)
• Use the following operation: BatchDisassociateClientDeviceFromCoreDevice.
Manage core device endpoints
When you use cloud discovery, you store MQTT broker endpoints for core devices in the AWS IoT
Greengrass cloud service. Client devices connect to AWS IoT Greengrass to retrieve these endpoints and
other information for their associated core devices.
For each core device, you can choose to automatically or manually manage endpoints.
• Automatically manage endpoints with IP detector
You can deploy the IP detector component (p. 240) the automatically manage core device endpoints
for you if you have a non-complex network setup, such as where the client devices are on the same
network as the core device. You can't use the IP detector component if the core device is behind a
router that forwards the MQTT broker port to the core device, for example.
The IP detector component is also useful if you deploy to thing groups, because it manages the
endpoints for all core devices in the thing group. For more information, see Use IP detector to
automatically manage endpoints (p. 655).
654
AWS IoT Greengrass Developer Guide, Version 2
Manage core device endpoints
Note
If you use the IP detector component to manage endpoints, you must use the default port
8883 for the Moquette MQTT broker component (p. 365).
• Manually manage endpoints
If you can't use the IP detector component, you must manually manage core device endpoints. You
can update these endpoints with the console or the API. For more information, see Manually manage
endpoints (p. 655).
Topics
• Use IP detector to automatically manage endpoints (p. 655)
• Manually manage endpoints (p. 655)
Use IP detector to automatically manage endpoints
If you have a simple network setup, such as the client devices on the same network as the core device,
you can deploy the IP detector component (p. 240) to do the following:
• Monitor the Greengrass core device's local network connectivity information. This information includes
the core device's network endpoints and the port where the MQTT broker operates.
• Report the core device's connectivity information to the AWS IoT Greengrass cloud service.
The core device's AWS IoT policy must allow the greengrass:UpdateConnectivityInfo permission
to use the IP detector component. For more information, see AWS IoT policies for data plane
operations (p. 774) and Minimal AWS IoT policy to support client devices (p. 779).
The IP detector component overwrites endpoints that you set manually.
You can do either of the following to deploy the IP detector component:
• Use the Configure discovery page in the console. For more information, see Configure cloud discovery
(console) (p. 652).
• Create and revise deployments to include the IP detector. You can use the console, AWS CLI, or AWS
API to manage deployments. For more information, see Create deployments (p. 493).
Manually manage endpoints
You can manually manage MQTT broker endpoints for core devices.
Each MQTT broker endpoint has the following information:
Endpoint (HostAddress)
An IP address or DNS address where client devices can connect to an MQTT broker on the core
device.
Port (PortNumber)
The port where the MQTT broker operates on the core device.
You can configure this port on the Moquette MQTT broker component (p. 365), which defaults to
use port 8883.
Metadata (Metadata)
Additional metadata to provide to client devices that connect to this endpoint.
655
AWS IoT Greengrass Developer Guide, Version 2
Manage core device endpoints
Topics
• Manage endpoints (console) (p. 656)
• Manage endpoints (AWS CLI) (p. 656)
• Manage endpoints (API) (p. 656)
Manage endpoints (console)
You can use the AWS IoT Greengrass console to view, update, and remove endpoints for a core device.
To manage endpoints for a core device (console)
1. Navigate to the AWS IoT Greengrass console.
2. Choose Core devices.
3. Choose the core device to manage.
4. On the core device's details page, choose the Client devices tab.
5. In the MQTT broker endpoints section, you can see the core device's MQTT broker endpoints.
Choose Manage endpoints.
6. In the Manage endpoints modal, add or remove MQTT broker endpoints for the core device.
7. Choose Update.
Manage endpoints (AWS CLI)
You can use the AWS Command Line Interface (AWS CLI) to manage endpoints for a core device.
Note
Because client device support in AWS IoT Greengrass V2 is backward compatible with AWS
IoT Greengrass V1, you use AWS IoT Greengrass V1 API operations to manage core device
endpoints.
To get endpoints for a core device (AWS CLI)
• Use the following command: get-connectivity-info.
To update endpoints for a core device (AWS CLI)
• Use the following command: update-connectivity-info.
Manage endpoints (API)
You can use the AWS API to manage endpoints for a core device.
Note
Because client device support in AWS IoT Greengrass V2 is backward compatible with AWS IoT
Greengrass V1, you use AWS IoT Greengrass V1 API operations to manage endpoints.
To get endpoints for a core device (AWS API)
• Use the following operation: GetConnectivityInfo.
To update endpoints for a core device (AWS API)
• Use the following command: UpdateConnectivityInfo.
656
AWS IoT Greengrass Developer Guide, Version 2
Test communications
Test client device communications
Client devices can use the AWS IoT Device SDK to discover, connect, and communicate with a core device.
You can use the Greengrass discovery client in the AWS IoT Device SDK to use the Greengrass discovery
API (p. 664), which returns information about core devices to which a client device can connect. The API
response includes MQTT broker endpoints to connect and certificates to use to verify the identity of each
core device. Then, the client device can try each endpoint until it successfully connects to a core device.
Client devices can discover only core devices to which you associate them. Before you test
communications between a client device and a core device, you must associate the client device to the
core device. For more information, see Associate client devices (p. 652).
The Greengrass discovery API returns the core device MQTT broker endpoints that you specify. You can
use the IP detector component (p. 240) to manage these endpoints for you, or you can manually manage
them for each core device. For more information, see Manage core device endpoints (p. 654).
Note
To use the Greengrass discovery API, a client device must have the greengrass:Discover
permission. For more information, see Minimal AWS IoT policy for client devices (p. 780).
The AWS IoT Device SDK is available in multiple programming languages. For more information, see AWS
IoT Device SDKs in the AWS IoT Core Developer Guide.
Topics
• Test communications (Python) (p. 657)
• Test communications (C++) (p. 659)
• Test communications (JavaScript) (p. 661)
• Test communications (Java) (p. 663)
Test communications (Python)
In this section, you use Greengrass discovery sample in the AWS IoT Device SDK v2 for Python to test
communications between a client device and a core device.
Important
To use the AWS IoT Device SDK v2 for Python, a device must run Python 3.6 or later.
To test communications (AWS IoT Device SDK v2 for Python)
1. Download and install the AWS IoT Device SDK v2 for Python to the AWS IoT thing to connect as a
client device.
On the client device, do the following:
a. Clone the AWS IoT Device SDK v2 for Python repository to download it.
git clone https://github.com/aws/aws-iot-device-sdk-python-v2.git
b. Install the AWS IoT Device SDK v2 for Python.
python3 -m pip install --user ./aws-iot-device-sdk-python-v2
2. Change to the samples folder in the AWS IoT Device SDK v2 for Python.
cd aws-iot-device-sdk-python-v2/samples
657
AWS IoT Greengrass Developer Guide, Version 2
Test communications
3. Run the sample Greengrass discovery application. This application expects arguments that specify
the client device thing name, the MQTT topic and message to use, and the certificates that
authenticate and secure the connection. The following example sends a Hello World message to the
clients/MyClientDevice1/hello/world topic.
• Replace both instances of MyClientDevice1 with the client device's thing name.
• Replace ~/certs/AmazonRootCA1.pem with the path to the Amazon root CA certificate on the
client device.
• Replace ~/certs/device.pem.crt with the path to the device certificate on the client device.
• Replace ~/certs/private.pem.key with the path to the private key file on the client device.
• Replace us-east-1 with the AWS Region where your client device and core device operate.
python3 basic_discovery.py \
--thing-name MyClientDevice1 \
--topic 'clients/MyClientDevice1/hello/world' \
--message 'Hello World!' \
--root-ca ~/certs/AmazonRootCA1.pem \
--cert ~/certs/device.pem.crt \
--key ~/certs/private.pem.key \
--region us-east-1 \
--verbosity Warn
The discovery sample application sends the message 10 times and disconnects. It also subscribes
to the same topic where it publishes messages. If the output indicates that the application received
MQTT messages on the topic, the client device can successfully communicate with the core device.
Performing greengrass discovery...
awsiot.greengrass_discovery.DiscoverResponse(gg_groups=[awsiot.greengrass_discovery.GGGroup(gg_grou
coreDevice-MyGreengrassCore',
cores=[awsiot.greengrass_discovery.GGCore(thing_arn='arn:aws:iot:us-
east-1:123456789012:thing/MyGreengrassCore',
connectivity=[awsiot.greengrass_discovery.ConnectivityInfo(id='203.0.113.0',
host_address='203.0.113.0', metadata='', port=8883)])],
certificate_authorities=['-----BEGIN CERTIFICATE-----\nMIICiT...EXAMPLE=\n-----END
CERTIFICATE-----\n'])])
Trying core arn:aws:iot:us-east-1:123456789012:thing/MyGreengrassCore at host
203.0.113.0 port 8883
Connected!
Published topic clients/MyClientDevice1/hello/world: {"message": "Hello World!",
"sequence": 0}
Publish received on topic clients/MyClientDevice1/hello/world
b'{"message": "Hello World!", "sequence": 0}'
Published topic clients/MyClientDevice1/hello/world: {"message": "Hello World!",
"sequence": 1}
Publish received on topic clients/MyClientDevice1/hello/world
b'{"message": "Hello World!", "sequence": 1}'
...
Published topic clients/MyClientDevice1/hello/world: {"message": "Hello World!",
"sequence": 9}
Publish received on topic clients/MyClientDevice1/hello/world
b'{"message": "Hello World!", "sequence": 9}'
If the application outputs an error instead, see Troubleshooting Greengrass discovery
issues (p. 672).
658
AWS IoT Greengrass Developer Guide, Version 2
Test communications
You can also view the Greengrass logs on the core device to verify if the client device successfully
connects and sends messages. For more information, see Monitor AWS IoT Greengrass logs (p. 506).
Test communications (C++)
In this section, you use Greengrass discovery sample in the AWS IoT Device SDK v2 for C++ to test
communications between a client device and a core device.
To build the AWS IoT Device SDK v2 for C++, a device must have the following tools:
• C++ 11 or later
• CMake 3.1 or later
• One of the following compilers:
• GCC 4.8 or later
• Clang 3.9 or later
• MSVC 2015 or later
To test communications (AWS IoT Device SDK v2 for C++)
1. Download and build the AWS IoT Device SDK v2 for C++ to the AWS IoT thing to connect as a client
device.
On the client device, do the following:
a. Create a folder for the AWS IoT Device SDK v2 for C++ workspace, and change to it.
cd
mkdir iot-device-sdk-cpp
cd iot-device-sdk-cpp
b. Clone the AWS IoT Device SDK v2 for C++ repository to download it. The --recursive flag
specifies to download submodules.
git clone --recursive https://github.com/aws/aws-iot-device-sdk-cpp-v2.git
c. Create a folder for the AWS IoT Device SDK v2 for C++ build output, and change to it.
mkdir aws-iot-device-sdk-cpp-v2-build
cd aws-iot-device-sdk-cpp-v2-build
d. Build the AWS IoT Device SDK v2 for C++.
cmake -DCMAKE_INSTALL_PREFIX="~/iot-device-sdk-cpp" -
DCMAKE_BUILD_TYPE="Release" ../aws-iot-device-sdk-cpp-v2
cmake --build . --target install
2. Build the Greengrass discovery sample application in the AWS IoT Device SDK v2 for C++. Do the
following:
a. Change to the Greengrass discovery sample folder in the AWS IoT Device SDK v2 for C++.
cd ../aws-iot-device-sdk-cpp-v2/samples/greengrass/basic_discovery
b. Create a folder for the Greengrass discovery sample build output, and change to it.
659
AWS IoT Greengrass Developer Guide, Version 2
Test communications
mkdir build
cd build
c. Build the Greengrass discovery sample application.
cmake -DCMAKE_PREFIX_PATH="~/iot-device-sdk-cpp" -DCMAKE_BUILD_TYPE="Release" ..
cmake --build . --config "Release
3. Run the sample Greengrass discovery application. This application expects arguments that specify
the client device thing name, the MQTT topic to use, and the certificates that authenticate and
secure the connection. The following example subscribes to the clients/MyClientDevice1/
hello/world topic and publishes a message that you enter on the command line to the same
topic.
• Replace both instances of MyClientDevice1 with the client device's thing name.
• Replace ~/certs/AmazonRootCA1.pem with the path to the Amazon root CA certificate on the
client device.
• Replace ~/certs/device.pem.crt with the path to the device certificate on the client device.
• Replace ~/certs/private.pem.key with the path to the private key file on the client device.
• Replace us-east-1 with the AWS Region where your client device and core device operate.
./basic-discovery \
--thing_name MyClientDevice1 \
--topic 'clients/MyClientDevice1/hello/world' \
--ca_file ~/certs/AmazonRootCA1.pem \
--cert ~/certs/device.pem.crt \
--key ~/certs/private.pem.key \
--region us-east-1
The discovery sample application subscribes to the topic and prompts you to enter a message to
publish.
Connecting to group greengrassV2-coreDevice-MyGreengrassCore with thing arn
arn:aws:iot:us-east-1:123456789012:thing/MyGreengrassCore, using endpoint
203.0.113.0:8883
Connected to group greengrassV2-coreDevice-MyGreengrassCore, using connection to
203.0.113.0:8883
Successfully subscribed to clients/MyClientDevice1/hello/world
Enter the message you want to publish to topic clients/MyClientDevice1/hello/world and
press enter. Enter 'exit' to exit this program.
If the application outputs an error instead, see Troubleshooting Greengrass discovery
issues (p. 672).
4. Enter a message, such as Hello World!.
Enter the message you want to publish to topic clients/MyClientDevice1/hello/world and
press enter. Enter 'exit' to exit this program.
Hello World!
If the output indicates that the application received the MQTT message on the topic, the client
device can successfully communicate with the core device.
Operation on packetId 2 Succeeded
Publish received on topic clients/MyClientDevice1/hello/world
660
AWS IoT Greengrass Developer Guide, Version 2
Test communications
Message:
Hello World!
You can also view the Greengrass logs on the core device to verify if the client device successfully
connects and sends messages. For more information, see Monitor AWS IoT Greengrass logs (p. 506).
Test communications (JavaScript)
In this section, you use Greengrass discovery sample in the AWS IoT Device SDK v2 for JavaScript to test
communications between a client device and a core device.
Important
To use the AWS IoT Device SDK v2 for JavaScript, a device must run Node v10.0 or later.
To test communications (AWS IoT Device SDK v2 for JavaScript)
1. Download and install the AWS IoT Device SDK v2 for JavaScript to the AWS IoT thing to connect as a
client device.
On the client device, do the following:
a. Clone the AWS IoT Device SDK v2 for JavaScript repository to download it.
git clone https://github.com/aws/aws-iot-device-sdk-js-v2.git
b. Install the AWS IoT Device SDK v2 for JavaScript.
cd aws-iot-device-sdk-js-v2
npm install
2. Change to the Greengrass discovery sample folder in the AWS IoT Device SDK v2 for JavaScript.
cd samples/node/basic_discovery
3. Install the Greengrass discovery sample application.
npm install
4. Run the sample Greengrass discovery application. This application expects arguments that specify
the client device thing name, the MQTT topic and message to use, and the certificates that
authenticate and secure the connection. The following example sends a Hello World message to the
clients/MyClientDevice1/hello/world topic.
• Replace both instances of MyClientDevice1 with the client device's thing name.
• Replace ~/certs/AmazonRootCA1.pem with the path to the Amazon root CA certificate on the
client device.
• Replace ~/certs/device.pem.crt with the path to the device certificate on the client device.
• Replace ~/certs/private.pem.key with the path to the private key file on the client device.
• Replace us-east-1 with the AWS Region where your client device and core device operate.
node dist/index.js \
--thing_name MyClientDevice1 \
--topic 'clients/MyClientDevice1/hello/world' \
--message 'Hello World!' \
--ca_file ~/certs/AmazonRootCA1.pem \
--cert ~/certs/device.pem.crt \
661
AWS IoT Greengrass Developer Guide, Version 2
Test communications
--key ~/certs/private.pem.key \
--region us-east-1 \
--verbose warn
The discovery sample application sends the message 10 times and disconnects. It also subscribes
to the same topic where it publishes messages. If the output indicates that the application received
MQTT messages on the topic, the client device can successfully communicate with the core device.
Discovery Response:
{"gg_groups":[{"gg_group_id":"greengrassV2-coreDevice-
MyGreengrassCore","cores":[{"thing_arn":"arn:aws:iot:us-
east-1:123456789012:thing/MyGreengrassCore","connectivity":
[{"id":"203.0.113.0","host_address":"203.0.113.0","port":8883,"metadata":""}]}],"certificate_author
["-----BEGIN CERTIFICATE-----\nMIICiT...EXAMPLE=\n-----END CERTIFICATE-----\n"]}]}
Trying
endpoint={"id":"203.0.113.0","host_address":"203.0.113.0","port":8883,"metadata":""}
[WARN] [2021-06-12T00:46:45Z] [00007f90c0e8d700] [socket] - id=0x7f90b8018710 fd=26:
setsockopt() for NO_SIGNAL failed with errno 92. If you are having SIGPIPE signals
thrown, you may want to install a signal trap in your application layer.
Connected to
endpoint={"id":"203.0.113.0","host_address":"203.0.113.0","port":8883,"metadata":""}
Publish received. topic:"clients/MyClientDevice1/hello/world" dup:false qos:0
retain:false
{"message":"Hello World!","sequence":1}
Publish received. topic:"clients/MyClientDevice1/hello/world" dup:false qos:0
retain:false
{"message":"Hello World!","sequence":2}
Publish received. topic:"clients/MyClientDevice1/hello/world" dup:false qos:0
retain:false
{"message":"Hello World!","sequence":3}
Publish received. topic:"clients/MyClientDevice1/hello/world" dup:false qos:0
retain:false
{"message":"Hello World!","sequence":4}
Publish received. topic:"clients/MyClientDevice1/hello/world" dup:false qos:0
retain:false
{"message":"Hello World!","sequence":5}
Publish received. topic:"clients/MyClientDevice1/hello/world" dup:false qos:0
retain:false
{"message":"Hello World!","sequence":6}
Publish received. topic:"clients/MyClientDevice1/hello/world" dup:false qos:0
retain:false
{"message":"Hello World!","sequence":7}
Publish received. topic:"clients/MyClientDevice1/hello/world" dup:false qos:0
retain:false
{"message":"Hello World!","sequence":8}
Publish received. topic:"clients/MyClientDevice1/hello/world" dup:false qos:0
retain:false
{"message":"Hello World!","sequence":9}
Publish received. topic:"clients/MyClientDevice1/hello/world" dup:false qos:0
retain:false
{"message":"Hello World!","sequence":10}
Complete!
If the application outputs an error instead, see Troubleshooting Greengrass discovery
issues (p. 672).
You can also view the Greengrass logs on the core device to verify if the client device successfully
connects and sends messages. For more information, see Monitor AWS IoT Greengrass logs (p. 506).
662
AWS IoT Greengrass Developer Guide, Version 2
Test communications
Test communications (Java)
In this section, you use Greengrass discovery sample in the AWS IoT Device SDK v2 for Java to test
communications between a client device and a core device.
Important
To build the AWS IoT Device SDK v2 for Java, a device must have the following tools:
• Java 8 or later, with JAVA_HOME pointing to the Java folder.
• Apache Maven
To test communications (AWS IoT Device SDK v2 for Java)
1. Download and build the AWS IoT Device SDK v2 for Java to the AWS IoT thing to connect as a client
device.
On the client device, do the following:
a. Clone the AWS IoT Device SDK v2 for Java repository to download it.
git clone https://github.com/aws/aws-iot-device-sdk-java-v2.git
b. Change to the AWS IoT Device SDK v2 for Java folder.
c. Build the AWS IoT Device SDK v2 for Java.
cd aws-iot-device-sdk-java-v2
mvn versions:use-latest-versions -Dincludes="software.amazon.awssdk.crt*"
mvn clean install
2. Run the sample Greengrass discovery application. This application expects arguments that specify
the client device thing name, the MQTT topic to use, and the certificates that authenticate and
secure the connection. The following example subscribes to the clients/MyClientDevice1/
hello/world topic and publishes a message that you enter on the command line to the same
topic.
• Replace both instances of MyClientDevice1 with the client device's thing name.
• Replace $HOME/certs/AmazonRootCA1.pem with the path to the Amazon root CA certificate on
the client device.
• Replace $HOME/certs/device.pem.crt with the path to the device certificate on the client
device.
• Replace $HOME/certs/private.pem.key with the path to the private key file on the client
device.
• Replace us-east-1 with the AWS Region where your client device and core device operate.
DISCOVERY_SAMPLE_ARGS="--thingName MyClientDevice1 \
--topic 'clients/MyClientDevice1/hello/world' \
--rootca $HOME/certs/AmazonRootCA1.pem \
--cert $HOME/certs/device.pem.crt \
--key $HOME/certs/private.pem.key \
--region us-east-1"
mvn exec:java -pl samples/Greengrass \
-Dexec.mainClass=greengrass.BasicDiscovery \
-Dexec.args="$DISCOVERY_SAMPLE_ARGS"
663
AWS IoT Greengrass Developer Guide, Version 2
Greengrass discovery RESTful API
The discovery sample application subscribes to the topic and prompts you to enter a message to
publish.
Connecting to group ID greengrassV2-coreDevice-MyGreengrassCore, with thing
arn arn:aws:iot:us-east-1:123456789012:thing/MyGreengrassCore, using endpoint
203.0.113.0:8883
Started a clean session
Enter the message you want to publish to topic clients/MyClientDevice1/hello/world and
press Enter. Type 'exit' or 'quit' to exit this program:
If the application outputs an error instead, see Troubleshooting Greengrass discovery
issues (p. 672).
3. Enter a message, such as Hello World!.
Enter the message you want to publish to topic clients/MyClientDevice1/hello/world and
press Enter. Type 'exit' or 'quit' to exit this program:
Hello World!
If the output indicates that the application received the MQTT message on the topic, the client
device can successfully communicate with the core device.
Message received on topic clients/MyClientDevice1/hello/world: Hello World!
You can also view the Greengrass logs on the core device to verify if the client device successfully
connects and sends messages. For more information, see Monitor AWS IoT Greengrass logs (p. 506).
Greengrass discovery RESTful API
AWS IoT Greengrass provides the Discover API operation that client devices can use to identify
Greengrass core devices where they can connect. Client devices use this data plane operation to
retrieve information required to connect to Greengrass core devices where you associate them with the
BatchAssociateClientDeviceWithCoreDevice API operation. When a client device comes online, it can
connect to the AWS IoT Greengrass cloud service and use the discovery API to find:
• The IP address and port for each associated Greengrass core device.
• The core device CA certificate, which client devices can use to authenticate the Greengrass core device.
Note
Client devices can also use the discovery client in the AWS IoT Device SDK to discover
connectivity information for Greengrass core devices. The discovery client uses the discovery
API. For more information, see the following:
• Test client device communications (p. 657)
• Greengrass Discovery RESTful API in the AWS IoT Greengrass Version 1 Developer Guide.
To use this API operation, send HTTP requests to the discovery API on the Greengrass data plane
endpoint. This API endpoint has the following format.
https://greengrass-ats.iot.region.amazonaws.com:port/greengrass/discover/thing/thing-name
For a list of supported AWS Regions and endpoints for the AWS IoT Greengrass discovery API, see AWS
IoT Greengrass V2 endpoints and quotas in the AWS General Reference. This API operation is available
664
AWS IoT Greengrass Developer Guide, Version 2
Greengrass discovery RESTful API
only on the Greengrass data plane endpoint. The control plane endpoint that you use to manage
components and deployments is different from the data plane endpoint.
Note
The discovery API is the same for AWS IoT Greengrass V1 and AWS IoT Greengrass V2. If you
have client devices that connect to a AWS IoT Greengrass V1 core, you can connect them to
AWS IoT Greengrass V2 core devices without changing the code on the client devices. For
more information, see Greengrass Discovery RESTful API in the AWS IoT Greengrass Version 1
Developer Guide.
Topics
• Discovery authentication and authorization (p. 665)
• Request (p. 665)
• Response (p. 666)
• Example discover response documents (p. 666)
• Test the discovery API with cURL (p. 667)
Discovery authentication and authorization
To use the discovery API to retrieve connectivity information, a client device must use TLS mutual
authentication with an X.509 client certificate to authenticate. For more information, see X.509 client
certificates in the AWS IoT Core Developer Guide.
A client device must also have permission to perform the greengrass:Discover action. The following
example AWS IoT policy allows an AWS IoT thing named MyClientDevice1 to perform Discover for
itself.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "greengrass:Discover",
"Resource": [
"arn:aws:iot:us-west-2:123456789012:thing/MyClientDevice1"
]
}
]
}
Important
Thing policy variables (iot:Connection.Thing.*) aren't supported for in AWS IoT policies for
core devices or Greengrass data plane operations. Instead, you can use a wildcard that matches
multiple devices that have similar names. For example, you can specify MyGreengrassDevice*
to match MyGreengrassDevice1, MyGreengrassDevice2, and so on.
For more information, see AWS IoT Core policies in the AWS IoT Core Developer Guide.
Request
The request contains the standard HTTP headers and is sent to the Greengrass discovery endpoint, as
shown in the following examples.
The port number depends on whether the core device is configured to send HTTPS traffic over port 8443
or port 443. For more information, see the section called “Connect on port 443 or through a network
proxy” (p. 165).
665
AWS IoT Greengrass Developer Guide, Version 2
Greengrass discovery RESTful API
Note
These examples use the Amazon Trust Services (ATS) endpoint, which works with the
recommended ATS root CA certificates. Endpoints must match the root CA certificate type.
Port 8443
HTTP GET https://greengrass-ats.iot.region.amazonaws.com:8443/greengrass/discover/
thing/thing-name
Port 443
HTTP GET https://greengrass-ats.iot.region.amazonaws.com:443/greengrass/discover/
thing/thing-name
Note
Clients that connect on port 443 must implement the Application Layer Protocol
Negotiation (ALPN) TLS extension and pass x-amzn-http-ca as the ProtocolName in the
ProtocolNameList. For more information, see Protocols in the AWS IoT Developer Guide.
Response
Upon success, the response includes the standard HTTP headers plus the following code and body:
HTTP 200
BODY: response document
For more information, see Example discover response documents (p. 666).
Example discover response documents
Because AWS IoT Greengrass V2 uses the same discovery API as AWS IoT Greengrass V1, the response
organizes information according to AWS IoT Greengrass V1 concepts, such as Greengrass groups. The
response contains a list of Greengrass groups. In AWS IoT Greengrass V2, each core device is in its own
group, where the group contains only that core device and its connectivity information.
The following document shows the response for a client device that is associated to one Greengrass core
device. The core device has one endpoint and one CA certificate.
{
"GGGroups": [
{
"GGGroupId": "greengrassV2-coreDevice-core-device-01-thing-name",
"Cores": [
{
"thingArn": "core-device-01-thing-arn",
"Connectivity": [
{
"id": "core-device-01-connection-id",
"hostAddress": "core-device-01-address",
"portNumber": core-device-01-port,
"metadata": "core-device-01-description"
}
]
}
],
"CAs": [
"-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----"
]
}
666
AWS IoT Greengrass Developer Guide, Version 2
Greengrass discovery RESTful API
]
}
The following document shows the response for a client device that is associated to two core devices.
The core devices have multiple endpoints and multiple group CA certificates.
{
"GGGroups": [
{
"GGGroupId": "greengrassV2-coreDevice-core-device-01-thing-name",
"Cores": [
{
"thingArn": "core-device-01-thing-arn",
"Connectivity": [
{
"id": "core-device-01-connection-id",
"hostAddress": "core-device-01-address",
"portNumber": core-device-01-port,
"metadata": "core-device-01-connection-1-description"
},
{
"id": "core-device-01-connection-id-2",
"hostAddress": "core-device-01-address-2",
"portNumber": core-device-01-port-2,
"metadata": "core-device-01-connection-2-description"
}
]
}
],
"CAs": [
"-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----",
"-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----",
"-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----"
]
},
{
"GGGroupId": "greengrassV2-coreDevice-core-device-02-thing-name",
"Cores": [
{
"thingArn":"core-device-02-thing-arn",
"Connectivity" : [
{
"id": "core-device-02-connection-id",
"hostAddress": "core-device-02-address",
"portNumber": core-device-02-port,
"metadata": "core-device-02-connection-1-description"
}
]
}
],
"CAs": [
"-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----",
"-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----",
"-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----"
]
}
]
}
Test the discovery API with cURL
If you have cURL installed, you can test the discovery API. The following example specifies a client
device's certificates to authenticate a request to the Greengrass discovery API endpoint.
667
AWS IoT Greengrass Developer Guide, Version 2
Relay MQTT messages between
client devices and AWS IoT Core
curl -i \
--cert 1a23bc4d56.cert.pem \
--key 1a23bc4d56.private.key \
https://greengrass-ats.iot.us-west-2.amazonaws.com:8443/greengrass/discover/
thing/MyClientDevice1
Note
The -i argument specifies to output HTTP response headers. You can use this option to help
identify errors.
If the request succeeds, this command outputs a response similar to the following example.
{
"GGGroups": [
{
"GGGroupId": "greengrassV2-coreDevice-MyGreengrassCore",
"Cores": [
{
"thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyGreengrassCore",
"Connectivity": [
{
"Id": "AUTOIP_192.168.1.4_1",
"HostAddress": "192.168.1.5",
"PortNumber": 8883,
"Metadata": ""
}
]
}
],
"CAs": [
"-----BEGIN CERTIFICATE-----\ncert-contents\n-----END CERTIFICATE-----\n"
]
}
]
}
If the command outputs an error, see Troubleshooting Greengrass discovery issues (p. 672).
Relay MQTT messages between client devices and
AWS IoT Core
You can relay MQTT messages and other data between client devices and AWS IoT Core. Client devices
connect to the MQTT broker component that runs on the core device. By default, core devices don't relay
MQTT messages or data between client devices and AWS IoT Core. Client devices can communicate only
with each other over MQTT by default.
To relay MQTT messages between client devices and AWS IoT Core, configure the MQTT bridge
component (p. 360) to do the following:
• Relay messages from client devices to AWS IoT Core.
• Relay messages from AWS IoT Core to client devices.
Note
The MQTT bridge uses QoS 1 to publish and subscribe to AWS IoT Core, even when a client
device uses QoS 0 to publish and subscribe to the local MQTT broker. As a result, you might
668
AWS IoT Greengrass Developer Guide, Version 2
Configure and deploy the MQTT bridge component
observe additional latency when you relay MQTT messages from client devices on the local
MQTT broker to AWS IoT Core. For more information about MQTT configuration on core devices,
see Configure MQTT timeouts and cache settings (p. 170).
Topics
• Configure and deploy the MQTT bridge component (p. 669)
• Relay MQTT messages (p. 669)
Configure and deploy the MQTT bridge component
The MQTT bridge component consumes a list of topic mappings that each specify a message source and
a message destination. To relay messages between client devices and AWS IoT Core, deploy the MQTT
bridge component, and specify each source and destination topic in the component configuration.
To deploy the MQTT bridge component to a core device or group of core devices, create a
deployment (p. 493) that includes the aws.greengrass.clientdevices.mqtt.Bridge component.
Specify the topic mappings, mqttTopicMapping in the MQTT bridge component configuration in the
deployment.
The following example defines a deployment that configures the MQTT bridge component to relay
messages on topics that match the clients/+/hello/world topic filter from client devices to AWS
IoT Core. The merge configuration update requires a serialized JSON object. For more information, see
Update component configurations (p. 500).
Console
{
"mqttTopicMapping": {
"HelloWorldIotCore": {
"topic": "clients/+/hello/world",
"source": "LocalMqtt",
"target": "IotCore"
}
}
}
AWS CLI
{
"components": {
"aws.greengrass.clientdevices.mqtt.Bridge": {
"version": "2.0.0",
"configurationUpdate": {
"merge": "{\"mqttTopicMapping\":{\"HelloWorldIotCore\":{\"topic"\:\"clients/+/
hello/world\",\"source\":\"LocalMqtt\",\"target\":\"IotCore\"}}}"
}
}
...
}
}
Relay MQTT messages
To relay MQTT messages between client devices and AWS IoT Core, configure and deploy the MQTT
Bridge component (p. 669) and specify the topics to relay.
669
AWS IoT Greengrass Developer Guide, Version 2
Interact with client devices in components
Example Example: Relay messages on a topic from client devices to AWS IoT Core
The following MQTT bridge component configuration specifies relaying messages on topics that match
the clients/+/hello/world/event topic filter from client devices to AWS IoT Core.
{
"mqttTopicMapping": {
"HelloWorldEvent": {
"topic": "clients/+/hello/world/event",
"source": "LocalMqtt",
"target": "IotCore"
}
}
}
Example Example: Relay messages on a topic from AWS IoT Core to client devices
The following MQTT bridge component configuration specifies relaying messages on topics that match
the clients/+/hello/world/event/response topic filter from AWS IoT Core to client devices.
{
"mqttTopicMapping": {
"HelloWorldEventConfirmation": {
"topic": "clients/+/hello/world/event/response",
"source": "IotCore",
"target": "LocalMqtt"
}
}
}
Interact with client devices in components
You can develop custom Greengrass components that interact with client devices connected to a core
device. For example, you can develop components that do the following:
• Act on MQTT messages from client devices and send data to AWS Cloud destinations.
• Send MQTT messages to client devices to initiate actions.
Client devices connect to and communicate with a core device through the MQTT broker component that
runs on the core device. By default, client devices can communicate only with each other over MQTT, and
Greengrass components can't receive these MQTT messages or send messages to client devices.
Greengrass components use the local publish/subscribe interface (p. 561) to communicate on a core
device. To communicate with client devices in Greengrass components, configure the MQTT bridge
component (p. 360) to do the following:
• Relay MQTT messages from client devices to local publish/subscribe.
• Relay MQTT messages from local publish/subscribe to client devices.
Topics
• Configure and deploy the MQTT bridge component (p. 671)
• Receive MQTT messages from client devices (p. 671)
• Send MQTT messages to client devices (p. 672)
670
AWS IoT Greengrass Developer Guide, Version 2
Configure and deploy the MQTT bridge component
Configure and deploy the MQTT bridge component
The MQTT bridge component consumes a list of topic mappings that each specify a message source and
a message destination. To communicate with client devices, deploy the MQTT bridge component, and
specify each source and destination topic in the component configuration.
To deploy the MQTT bridge component to a core device or group of core devices, create a
deployment (p. 493) that includes the aws.greengrass.clientdevices.mqtt.Bridge component.
Specify the topic mappings, mqttTopicMapping in the MQTT bridge component configuration in the
deployment.
The following example defines a deployment that configures the MQTT bridge component to relay the
clients/MyClientDevice1/hello/world topic from client devices to local publish/subscribe broker.
The merge configuration update requires a serialized JSON object. For more information, see Update
component configurations (p. 500).
Console
{
"mqttTopicMapping": {
"HelloWorldPubsub": {
"topic": "clients/MyClientDevice1/hello/world",
"source": "LocalMqtt",
"target": "Pubsub"
}
}
}
AWS CLI
{
"components": {
"aws.greengrass.clientdevices.mqtt.Bridge": {
"version": "2.0.0",
"configurationUpdate": {
"merge": "\"mqttTopicMapping\":{\"HelloWorldPubsub\":{\"topic\":\"clients/
MyClientDevice1/hello/world\",\"source\":\"LocalMqtt\",\"target\":\"Pubsub\"}}}"
}
}
...
}
}
You can use MQTT topic wildcards to relay messages on topics that match a topic filter. For more
information, see MQTT bridge component configuration (p. 361).
Receive MQTT messages from client devices
You can subscribe to the local publish/subscribe topics that you configure for the MQTT bridge
component to receive messages from client devices.
To receive MQTT messages from client devices in custom components
1. Configure and deploy the MQTT bridge component (p. 671) to relay messages from an MQTT topic
where client devices publish to a local publish/subscribe topic.
2. Use the local publish/subscribe IPC interface to subscribe to the topic where the MQTT bridge
relays messages. For more information, see Publish/subscribe local messages (p. 561) and
SubscribeToTopic (p. 565).
671
AWS IoT Greengrass Developer Guide, Version 2
Send MQTT messages to client devices
The Connect and test client devices tutorial (p. 638) includes a section where you develop a component
that subscribes to messages from a client device. For more information, see Develop a component that
interacts with client devices (p. 645).
Send MQTT messages to client devices
You can publish to the local publish/subscribe topics that you configure for the MQTT bridge component
to send messages to client devices.
To publish MQTT messages to client devices in custom components
1. Configure and deploy the MQTT bridge component (p. 671) to relay messages from a local
publish/subscribe topic to an MQTT topic where client devices subscribe.
2. Use the local publish/subscribe IPC interface to publish to the topic where the MQTT bridge
relays messages. For more information, see Publish/subscribe local messages (p. 561) and
PublishToTopic (p. 562).
Troubleshooting client devices
Use the troubleshooting information and solutions in this section to help resolve issues with Greengrass
client devices and client device components.
Topics
• Greengrass discovery issues (p. 672)
Greengrass discovery issues
Use the following information to troubleshoot issues with Greengrass discovery. These issues can occur
when client devices use the Greengrass discovery API (p. 664) to identify a Greengrass core device to
which they can connect.
Topics
• Greengrass discovery issues (HTTP API) (p. 672)
• Greengrass discovery issues (AWS IoT Device SDK v2 for Python) (p. 673)
• Greengrass discovery issues (AWS IoT Device SDK v2 for C++) (p. 674)
• Greengrass discovery issues (AWS IoT Device SDK v2 for JavaScript) (p. 675)
• Greengrass discovery issues (AWS IoT Device SDK v2 for Java) (p. 676)
Greengrass discovery issues (HTTP API)
Use the following information to troubleshoot issues with Greengrass discovery. You might see these
errors if you test the discovery API with cURL (p. 667).
Topics
• curl: (52) Empty reply from server (p. 672)
• HTTP 403: {"message":null,"traceId":"a1b2c3d4-5678-90ab-cdef-11111EXAMPLE"} (p. 673)
• HTTP 404: {"errorMessage":"The thing provided for discovery was not found"} (p. 673)
curl: (52) Empty reply from server
You might see this error if you specify an inactive AWS IoT certificate in the request.
672
AWS IoT Greengrass Developer Guide, Version 2
Greengrass discovery issues
Check that the client device has an attached certificate, and that the certificate is active. For more
information, see Attach a thing or policy to a client certificate and Activate or deactivate a client
certificate in the AWS IoT Core Developer Guide.
HTTP 403: {"message":null,"traceId":"a1b2c3d4-5678-90ab-
cdef-11111EXAMPLE"}
You might see this error if the client device doesn't have permission to call greengrass:Discover for
itself.
Check that the client device's certificate has a policy that allows greengrass:Discover. You can't use
thing policy variables (iot:Connection.Thing.*) in the Resource section for this permission. For
more information, see Discovery authentication and authorization (p. 665).
HTTP 404: {"errorMessage":"The thing provided for discovery was not found"}
You might see this error in the following cases:
• The client device isn't associated to any Greengrass core devices or AWS IoT Greengrass V1 groups.
• None of the client device's associated Greengrass core devices or AWS IoT Greengrass V1 groups have
an MQTT broker endpoint.
Check that the client device is associated to the core device to which you want it to connect. Then, check
that the core device has at least one MQTT broker endpoint. For more information, see Associate client
devices (p. 652) and Manage core device endpoints (p. 654).
Greengrass discovery issues (AWS IoT Device SDK v2 for Python)
Use the following information to troubleshoot issues with Greengrass discovery in the AWS IoT Device
SDK v2 for Python.
Topics
• awscrt.exceptions.AwsCrtError: AWS_ERROR_HTTP_CONNECTION_CLOSED: The connection has
closed or is closing. (p. 673)
• awsiot.greengrass_discovery.DiscoveryException: ('Error during discover call: response_code=403',
403) (p. 673)
• awsiot.greengrass_discovery.DiscoveryException: ('Error during discover call: response_code=404',
404) (p. 674)
awscrt.exceptions.AwsCrtError: AWS_ERROR_HTTP_CONNECTION_CLOSED: The
connection has closed or is closing.
You might see this error if you specify an inactive AWS IoT certificate in the request.
Check that the client device has an attached certificate, and that the certificate is active. For more
information, see Attach a thing or policy to a client certificate and Activate or deactivate a client
certificate in the AWS IoT Core Developer Guide.
awsiot.greengrass_discovery.DiscoveryException: ('Error during discover call:
response_code=403', 403)
You might see this error if the client device doesn't have permission to call greengrass:Discover for
itself.
673
AWS IoT Greengrass Developer Guide, Version 2
Greengrass discovery issues
Check that the client device's certificate has a policy that allows greengrass:Discover. You can't use
thing policy variables (iot:Connection.Thing.*) in the Resource section for this permission. For
more information, see Discovery authentication and authorization (p. 665).
awsiot.greengrass_discovery.DiscoveryException: ('Error during discover call:
response_code=404', 404)
You might see this error in the following cases:
• The client device isn't associated to any Greengrass core devices or AWS IoT Greengrass V1 groups.
• None of the client device's associated Greengrass core devices or AWS IoT Greengrass V1 groups have
an MQTT broker endpoint.
Check that the client device is associated to the core device to which you want it to connect. Then, check
that the core device has at least one MQTT broker endpoint. For more information, see Associate client
devices (p. 652) and Manage core device endpoints (p. 654).
Greengrass discovery issues (AWS IoT Device SDK v2 for C++)
Use the following information to troubleshoot issues with Greengrass discovery in the AWS IoT Device
SDK v2 for C++.
Topics
• aws-c-http: AWS_ERROR_HTTP_CONNECTION_CLOSED, The connection has closed or is
closing. (p. 674)
• aws-c-common: AWS_ERROR_UNKNOWN, Unknown error. (HTTP 403) (p. 674)
• aws-c-common: AWS_ERROR_UNKNOWN, Unknown error. (HTTP 404) (p. 674)
aws-c-http: AWS_ERROR_HTTP_CONNECTION_CLOSED, The connection has
closed or is closing.
You might see this error if you specify an inactive AWS IoT certificate in the request.
Check that the client device has an attached certificate, and that the certificate is active. For more
information, see Attach a thing or policy to a client certificate and Activate or deactivate a client
certificate in the AWS IoT Core Developer Guide.
aws-c-common: AWS_ERROR_UNKNOWN, Unknown error. (HTTP 403)
You might see this error if the client device doesn't have permission to call greengrass:Discover for
itself.
Check that the client device's certificate has a policy that allows greengrass:Discover. You can't use
thing policy variables (iot:Connection.Thing.*) in the Resource section for this permission. For
more information, see Discovery authentication and authorization (p. 665).
aws-c-common: AWS_ERROR_UNKNOWN, Unknown error. (HTTP 404)
You might see this error in the following cases:
• The client device isn't associated to any Greengrass core devices or AWS IoT Greengrass V1 groups.
• None of the client device's associated Greengrass core devices or AWS IoT Greengrass V1 groups have
an MQTT broker endpoint.
674
AWS IoT Greengrass Developer Guide, Version 2
Greengrass discovery issues
Check that the client device is associated to the core device to which you want it to connect. Then, check
that the core device has at least one MQTT broker endpoint. For more information, see Associate client
devices (p. 652) and Manage core device endpoints (p. 654).
Greengrass discovery issues (AWS IoT Device SDK v2 for
JavaScript)
Use the following information to troubleshoot issues with Greengrass discovery in the AWS IoT Device
SDK v2 for JavaScript.
Topics
• Error: aws-c-http: AWS_ERROR_HTTP_CONNECTION_CLOSED, The connection has closed or is
closing. (p. 675)
• Error: Discovery failed (headers: [object Object]) { response_code: 403 } (p. 675)
• Error: Discovery failed (headers: [object Object]) { response_code: 404 } (p. 675)
• Error: Discovery failed (headers: [object Object]) (p. 675)
Error: aws-c-http: AWS_ERROR_HTTP_CONNECTION_CLOSED, The connection
has closed or is closing.
You might see this error if you specify an inactive AWS IoT certificate in the request.
Check that the client device has an attached certificate, and that the certificate is active. For more
information, see Attach a thing or policy to a client certificate and Activate or deactivate a client
certificate in the AWS IoT Core Developer Guide.
Error: Discovery failed (headers: [object Object]) { response_code: 403 }
You might see this error if the client device doesn't have permission to call greengrass:Discover for
itself.
Check that the client device's certificate has a policy that allows greengrass:Discover. You can't use
thing policy variables (iot:Connection.Thing.*) in the Resource section for this permission. For
more information, see Discovery authentication and authorization (p. 665).
Error: Discovery failed (headers: [object Object]) { response_code: 404 }
You might see this error in the following cases:
• The client device isn't associated to any Greengrass core devices or AWS IoT Greengrass V1 groups.
• None of the client device's associated Greengrass core devices or AWS IoT Greengrass V1 groups have
an MQTT broker endpoint.
Check that the client device is associated to the core device to which you want it to connect. Then, check
that the core device has at least one MQTT broker endpoint. For more information, see Associate client
devices (p. 652) and Manage core device endpoints (p. 654).
Error: Discovery failed (headers: [object Object])
You might see this error (without an HTTP response code) when you run the Greengrass discovery
sample. This error can occur for multiple reasons.
• You might see this error if the client device doesn't have permission to call greengrass:Discover
for itself.
675
AWS IoT Greengrass Developer Guide, Version 2
Greengrass discovery issues
Check that the client device's certificate has a policy that allows greengrass:Discover. You can't
use thing policy variables (iot:Connection.Thing.*) in the Resource section for this permission.
For more information, see Discovery authentication and authorization (p. 665).
• You might see this error in the following cases:
• The client device isn't associated to any Greengrass core devices or AWS IoT Greengrass V1 groups.
• None of the client device's associated Greengrass core devices or AWS IoT Greengrass V1 groups
have an MQTT broker endpoint.
Check that the client device is associated to the core device to which you want it to connect. Then,
check that the core device has at least one MQTT broker endpoint. For more information, see Associate
client devices (p. 652) and Manage core device endpoints (p. 654).
Greengrass discovery issues (AWS IoT Device SDK v2 for Java)
Use the following information to troubleshoot issues with Greengrass discovery in the AWS IoT Device
SDK v2 for Java.
Topics
• software.amazon.awssdk.crt.CrtRuntimeException: Error Getting Response Status Code from
HttpStream. (aws_last_error: AWS_ERROR_HTTP_DATA_NOT_AVAILABLE(2062), This data is not yet
available.) (p. 676)
• java.lang.RuntimeException: Error x-amzn-ErrorType(403) (p. 676)
• java.lang.RuntimeException: Error x-amzn-ErrorType(404) (p. 676)
software.amazon.awssdk.crt.CrtRuntimeException: Error Getting
Response Status Code from HttpStream. (aws_last_error:
AWS_ERROR_HTTP_DATA_NOT_AVAILABLE(2062), This data is not yet
available.)
You might see this error if you specify an inactive AWS IoT certificate in the request.
Check that the client device has an attached certificate, and that the certificate is active. For more
information, see Attach a thing or policy to a client certificate and Activate or deactivate a client
certificate in the AWS IoT Core Developer Guide.
java.lang.RuntimeException: Error x-amzn-ErrorType(403)
You might see this error if the client device doesn't have permission to call greengrass:Discover for
itself.
Check that the client device's certificate has a policy that allows greengrass:Discover. You can't use
thing policy variables (iot:Connection.Thing.*) in the Resource section for this permission. For
more information, see Discovery authentication and authorization (p. 665).
java.lang.RuntimeException: Error x-amzn-ErrorType(404)
You might see this error in the following cases:
• The client device isn't associated to any Greengrass core devices or AWS IoT Greengrass V1 groups.
• None of the client device's associated Greengrass core devices or AWS IoT Greengrass V1 groups have
an MQTT broker endpoint.
676
AWS IoT Greengrass Developer Guide, Version 2
Greengrass discovery issues
Check that the client device is associated to the core device to which you want it to connect. Then, check
that the core device has at least one MQTT broker endpoint. For more information, see Associate client
devices (p. 652) and Manage core device endpoints (p. 654).
677
AWS IoT Greengrass Developer Guide, Version 2
Interact with shadows in components
Interact with device shadows
Greengrass devices can interact with AWS IoT device shadows using components. A shadow is a JSON
document that stores the current or desired state information for an AWS IoT thing. Shadows can make
a device’s state available to other AWS IoT Greengrass components whether the device is connected to
AWS IoT or not. Each AWS IoT device has its own classic, unnamed shadow. You can also create multiple
named shadows for each device.
Devices and services can create, update, and delete cloud shadows by using MQTT and the reserved
MQTT shadow topics, HTTP using the Device Shadow REST API, and the AWS CLI for AWS IoT.
The shadow manager (p. 383) component enables your Greengrass components to create, update, and
delete local shadows by using the local shadow service (p. 618) and the local publish/subscribe shadow
topics. The shadow manager also manages the storage of these local shadow documents on your core
device, and handles the synchronization of shadow state information with cloud shadows.
For more information about AWS IoT device shadow concepts, see AWS IoT Device Shadow service in the
AWS IoT Developer Guide.
Topics
• Interact with shadows in components (p. 678)
• Sync local device shadows with AWS IoT Core (p. 680)
Interact with shadows in components
You can develop custom components, including Lambda function components, that use the local shadow
service to read and modify local shadow documents and perform local state management of connected
devices.
Custom components interact with the local shadow service using the AWS IoT Greengrass Core IPC
libraries in the AWS IoT Device SDK. The shadow manager (p. 383) component enables the local shadow
service on your core device.
To deploy the shadow manager component to a Greengrass core device, create a deployment (p. 493)
that includes the aws.greengrass.ShadowManager component.
Note
By default, deploying the shadow manager component enables local shadow operations only.
To enable AWS IoT Greengrass to sync shadow state information for core device shadows or any
shadows for connected devices to the corresponding cloud shadow documents in AWS IoT Core,
you must create a configuration update for the shadow manager component that includes the
synchronize parameter. For more information, see Sync local device shadows with AWS IoT
Core (p. 680).
Topics
• Retrieve and modify shadow states (p. 678)
• React to shadow state changes (p. 679)
Retrieve and modify shadow states
The shadow IPC operations retrieve and update state information in local shadow documents. The
shadow manager component handles the storage of these shadow documents on your core device.
678
AWS IoT Greengrass Developer Guide, Version 2
React to shadow state changes
To modify local shadow states
1. Add access control policies to the recipe for your custom component to allow the component to
receive messages on local shadow topics. For example, the following example access control policy
allows the component to create, update, and delete the classic device shadow and the named
shadow myNamedShadow for the device MyThingName.
{
"accessControl": {
"aws.greengrass.ShadowManager": {
"policyId1": {
"policyDescription": "Allows access to shadows",
"operations": [
"aws.greengrass#GetThingShadow",
"aws.greengrass#UpdateThingShadow",
"aws.greengrass#DeleteThingShadow"
],
"resources": [
"$aws/things/MyThingName/shadow",
"$aws/things/MyThingName/shadow/name/myNamedShadow"
]
}
}
}
}
2. Use the shadow IPC operations to retrieve and modify shadow state information. For more
information about using shadow IPC operations in component code, see Interact with local
shadows (p. 618).
React to shadow state changes
Greengrass components use the local publish/subscribe interface to communicate on a core device. To
enable a custom component to react to shadow state changes, you can subscribe to the local publish/
subscribe topics. This allows the component to receive messages on the local shadow topics, and then
act on those messages.
Local shadow topics use the same format as the AWS IoT device shadow MQTT topics. For more
information about shadow topics, see Device Shadow MQTT topics in the AWS IoT Developer Guide.
To react to local shadow state changes
1. Add access control policies to the recipe for your custom component to allow the component to
receive messages on local shadow topics. For example, the following example access control policy
allows the custom com.example.MyShadowReactiveComponent to receive messages on the /
update/delta topic for the classic device shadow and the named shadow myNamedShadow for the
device MyThingName.
{
"accessControl": {
"aws.greengrass.ipc.pubsub": {
"com.example.MyShadowReactivenComponent:pubsub:1": {
"policyDescription": "Allows access to shadow pubsub topics",
"operations": [
"aws.greengrass#SubscribeToTopic"
],
"resources": [
"$aws/things/MyThingName/shadow/update/delta",
"$aws/things/MyThingName/shadow/name/myNamedShadow/update/delta"
]
679
AWS IoT Greengrass Developer Guide, Version 2
Sync local device shadows with AWS IoT Core
}
}
}
}
2. To initiate a custom action in a component, use SubscribeToTopic IPC operations to subscribe to
the shadow topics on which you want to receive messages. For more information about using local
publish/subscribe IPC operations in component code, see Publish/subscribe local messages (p. 561).
3. To invoke a Lambda function, use the event source configuration to provide the name of the shadow
topic and specify that it's a local publish/subscribe topic. For information about creating Lambda
function components, see Run AWS Lambda functions (p. 523).
Sync local device shadows with AWS IoT Core
The shadow manager component enables AWS IoT Greengrass to sync local device shadow states with
AWS IoT Core. You must modify the configuration of the shadow manager component to include the
synchronization configuration parameter, and specify the AWS IoT thing names for your devices, and
the shadows that you want to sync.
When you configure shadow manager to sync shadows, it syncs all state changes for specified shadows,
regardless of whether the changes occur in local shadow documents or in cloud shadow documents.
Topics
• Prerequisites (p. 680)
• Configure the shadow manager component (p. 680)
• Sync local shadows (p. 681)
Prerequisites
To sync local shadows to the AWS IoT Core, you must configure the Greengrass core device's AWS IoT
policy to allow the following AWS IoT Core shadow policy actions.
• iot:GetThingShadow
• iot:UpdateThingShadow
• iot:DeleteThingShadow
For more information about these AWS IoT Core policies, see AWS IoT Core policy actions in the AWS IoT
Developer Guide.
For more information about the minimal AWS IoT policy for core devices, see Minimal AWS IoT policy for
AWS IoT Greengrass V2 core devices (p. 777).
For more information about how to update a core device's AWS IoT policy, see Update a core device's
AWS IoT policy (p. 776).
Configure the shadow manager component
The shadow manager requires a list of shadow name mappings to sync shadow state information in local
shadow documents to cloud shadow documents in AWS IoT Core.
To sync shadow states, create a deployment (p. 493) that includes the
aws.greengrass.ShadowManager component, and specify the shadows that you want to sync in the
synchronize configuration parameter in the shadow manager configuration in the deployment.
680
AWS IoT Greengrass Developer Guide, Version 2
Sync local shadows
The following example configuration update instructs the shadow manager component to sync the
following shadows with AWS IoT Core:
• The classic shadow for the core device
• The named MyCoreShadow for the core device
• The classic shadow for an IoT thing named MyDevice2
• The named shadows MyShadowA and MyShadowB for a IoT thing named MyDevice1
{
"synchronize":{
"coreThing":{
"classic":true,
"namedShadows":["MyCoreShadow"]
},
"shadowDocuments":[
{
"thingName":"MyDevice1",
"classic":false,
"namedShadows":[
"MyShadowA",
"MyShadowB"
]
},
{
"thingName":"MyDevice2",
"classic":true,
"namedShadows":[ ]
}
]
}
}
Sync local shadows
When the Greengrass core device is connected to the AWS IoT cloud, the shadow manager performs the
following tasks for the shadows that you specify in the component configuration:
• Retrieves the reported state information from the cloud shadow document in AWS IoT Core.
• Updates locally stored shadow documents to synchronize the device state.
• Publishes the device’s current state to the cloud shadow document.
681
AWS IoT Greengrass Developer Guide, Version 2
Stream management workflow
Manage data streams on the AWS
IoT Greengrass Core
AWS IoT Greengrass stream manager makes it more efficient and reliable to transfer high-volume IoT
data to the AWS Cloud. Stream manager processes data streams on the AWS IoT Greengrass Core before
it exports them to the AWS Cloud. Stream manager integrates with common edge scenarios, such as
machine learning (ML) inference, where the AWS IoT Greengrass Core device processes and analyzes data
before it exports the data to the AWS Cloud or local storage destinations.
Stream manager provides a common interface to simplify custom component development so that you
don't need to build custom stream management functionality. Your components can use a standardized
mechanism to process high-volume streams and manage local data retention policies. You can define
policies for storage type, size, and data retention for each stream to control how stream manager
processes and exports data.
Stream manager works in environments with intermittent or limited connectivity. You can define
bandwidth use, timeout behavior, and how the AWS IoT Greengrass Core handles stream data when
it is connected or disconnected. You can also set priorities to control the order in which the AWS IoT
Greengrass Core exports streams to the AWS Cloud. This makes it possible for you to handle critical data
sooner than other data.
You can configure stream manager to automatically export data to the AWS Cloud for storage or further
processing and analysis. Stream manager supports exports to the following AWS Cloud destinations:
• Channels in AWS IoT Analytics. AWS IoT Analytics lets you perform advanced analysis on your data to
help make business decisions and improve machine learning models. For more information, see What
is AWS IoT Analytics? in the AWS IoT Analytics User Guide.
• Streams in Amazon Kinesis Data Streams. You can use Kinesis Data Streams to aggregate high-volume
data and load it into a data warehouse or MapReduce cluster. For more information, see What is
Amazon Kinesis Data Streams? in the Amazon Kinesis Data Streams Developer Guide.
• Asset properties in AWS IoT SiteWise. AWS IoT SiteWise lets you collect, organize, and analyze data
from industrial equipment at scale. For more information, see What is AWS IoT SiteWise? in the AWS
IoT SiteWise User Guide.
• Objects in Amazon Simple Storage Service Amazon S3. You can use Amazon S3 to store and retrieve
large amounts of data. For more information, see What is Amazon S3? in the Amazon Simple Storage
Service Developer Guide.
Stream management workflow
Your IoT applications interact with stream manager through the Stream Manager SDK.
In a simple workflow, a component on the AWS IoT Greengrass core consumes IoT data, such as time-
series temperature and pressure metrics. The component might filter or compress the data, and then
call the Stream Manager SDK to write the data to a stream in stream manager. Stream manager can
export the stream to the AWS Cloud automatically based on the policies that you define for the stream.
Components can also send data directly to local databases or storage repositories.
Your IoT applications can include multiple custom components that read or write to streams. These
components can read and write to streams to filter, aggregate, and analyze data on the AWS IoT
682
AWS IoT Greengrass Developer Guide, Version 2
Requirements
Greengrass core device. This makes it possible to respond quickly to local events and extract valuable
information before the data transfers from the core to the AWS Cloud or local destinations.
To get started, deploy the stream manager component to your AWS IoT Greengrass core device. In the
deployment, configure the stream manager component parameters to define settings that apply to all
streams on the Greengrass core device. Use these parameters to control how stream manager stores,
processes, and exports streams based on your business needs and environment constraints.
After you configure stream manager, you can create and deploy your IoT applications. These are typically
custom components that use StreamManagerClient in the Stream Manager SDK to create and interact
with streams. When you create a stream, you can define per-stream policies, such as export destinations,
priority, and persistence.
Requirements
The following requirements apply for using stream manager:
• Stream manager requires a minimum of 70 MB RAM in addition to the AWS IoT Greengrass Core
software. Your total memory requirement depends on your workload.
• AWS IoT Greengrass components must use the Stream Manager SDK to interact with stream manager.
The Stream Manager SDK is available in the following languages :
• Stream Manager SDK for Java (v1.1.0 or later)
• Stream Manager SDK for Node.js (v1.1.0 or later)
• Stream Manager SDK for Python (v1.1.0 or later)
• AWS IoT Greengrass components must specify the stream manager component
(aws.greengrass.StreamManager) as a dependency in their recipe to use stream manager.
Note
If you use stream manager to export data to the cloud, you can't upgrade version 2.0.7 of the
stream manager component to a version between v2.0.8 and v2.0.11. If you are deploying
stream manager for the first time, we strongly recommend that you deploy the latest version
of the stream manager component.
• If you define AWS Cloud export destinations for a stream, you must create your export targets and
grant access permissions in the Greengrass device role (p. 790). Depending on the destination, other
requirements might also apply. For more information, see:
• the section called “AWS IoT Analytics channels” (p. 711)
• the section called “Amazon Kinesis data streams” (p. 712)
• the section called “AWS IoT SiteWise asset properties” (p. 713)
• the section called “Amazon S3 objects” (p. 715)
You are responsible for maintaining these AWS Cloud resources.
Data security
When you use stream manager, be aware of the following security considerations.
Local data security
AWS IoT Greengrass does not encrypt stream data at rest or in transit between local components on the
core device.
683
AWS IoT Greengrass Developer Guide, Version 2
Client authentication
• Data at rest. Stream data is stored locally in a storage directory. For data security, AWS IoT
Greengrass relies on file permissions and full-disk encryption, if enabled. You can use the optional
STREAM_MANAGER_STORE_ROOT_DIR (p. 721) parameter to specify the storage directory. If you
change this parameter later to use a different storage directory, AWS IoT Greengrass does not delete
the previous storage directory or its contents.
• Data in transit locally. AWS IoT Greengrass does not encrypt stream data in local transit between data
sources, AWS IoT Greengrass components, the Stream Manager SDK, and stream manager.
• Data in transit to the AWS Cloud. Data streams exported by stream manager to the AWS Cloud use
standard AWS service client encryption with Transport Layer Security (TLS).
Client authentication
Stream manager clients use the Stream Manager SDK to communicate with stream manager. When client
authentication is enabled, only Greengrass components can interact with streams in stream manager.
When client authentication is disabled, any process running on the Greengrass core device can interact
with streams in stream manager. You should disable authentication only if your business case requires it.
You use the STREAM_MANAGER_AUTHENTICATE_CLIENT (p. 721) parameter to set the client
authentication mode. You can configure this parameter when you deploy the stream manager
component to core devices.
Enabled Disabled
Parameter value true (default and false
recommended)
Allowed clients Greengrass components on the Greengrass components on the
core device core device
Other processes running on the
Greengrass core device
See also
• the section called “Configure stream manager” (p. 720)
• the section called “Use StreamManagerClient to work with streams” (p. 695)
• the section called “Export configurations for supported cloud destinations” (p. 710)
Create custom components that use stream
manager
Use stream manager in custom Greengrass components to store, process, and export IoT device data. Use
the procedures and examples in this section to create component recipes, artifacts, and applications that
work with stream manager. For more information about how to develop and test components, see Create
AWS IoT Greengrass components (p. 442).
Topics
• Define component recipes that use stream manager (p. 685)
• Connect to stream manager in application code (p. 693)
684
AWS IoT Greengrass Developer Guide, Version 2
Define component recipes that use stream manager
Define component recipes that use stream manager
To use stream manager in a custom component, you must define the
aws.greengrass.StreamManager component as a dependency. You must also provide the Stream
Manager SDK. Complete the following tasks to download and use the Stream Manager SDK in the
language of your choice.
Use the Stream Manager SDK for Java
The Stream Manager SDK for Java is available as a JAR file that you can use to compile your component.
Then, you can create an application JAR that includes the Stream Manager SDK, define the application
JAR as a component artifact, and run the application JAR in the component lifecycle.
To use the Stream Manager SDK for Java
1. Download the Stream Manager SDK for Java JAR file.
2. Do one of the following to create component artifacts from your Java application and the Stream
Manager SDK JAR file:
• Build your application as a JAR file that includes the Stream Manager SDK JAR, and run this JAR
file in your component recipe.
• Define the Stream Manager SDK JAR as a component artifact. Add that artifact to the classpath
when you run your application in your component recipe.
Your component recipe might look like the following example. This component runs a modified
version of the StreamManagerS3.java example, where StreamManagerS3.jar includes the Stream
Manager SDK JAR.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.StreamManagerS3Java",
"ComponentVersion": "1.0.0",
"ComponentDescription": "Uses stream manager to upload a file to an S3 bucket.",
"ComponentPublisher": "Amazon",
"ComponentDependencies": {
"aws.greengrass.StreamManager": {
"VersionRequirement": "^2.0.0"
}
},
"Manifests": [
{
"Lifecycle": {
"Run": "java -jar {artifacts:path}/StreamManagerS3.jar"
},
"Artifacts": [
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.StreamManagerS3Java/1.0.0/StreamManagerS3.jar"
}
]
}
]
}
YAML
---
685
AWS IoT Greengrass Developer Guide, Version 2
Define component recipes that use stream manager
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.StreamManagerS3Java
ComponentVersion: 1.0.0
ComponentDescription: Uses stream manager to upload a file to an S3 bucket.
ComponentPublisher: Amazon
ComponentDependencies:
aws.greengrass.StreamManager:
VersionRequirement: "^2.0.0"
Manifests:
- Lifecycle:
Run: java -jar {artifacts:path}/StreamManagerS3.jar
Artifacts:
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.StreamManagerS3Java/1.0.0/StreamManagerS3.jar
For more information about how to develop and test components, see Create AWS IoT Greengrass
components (p. 442).
Use the Stream Manager SDK for Python
The Stream Manager SDK for Python is available as source code that you can include in your component.
Create a ZIP file of the Stream Manager SDK, define the ZIP file as a component artifact, and install the
SDK's requirements in the component lifecycle.
To use the Stream Manager SDK for Python
1. Clone or download the aws-greengrass-stream-manager-sdk-python repository.
git clone git@github.com:aws-greengrass/aws-greengrass-stream-manager-sdk-python.git
2. Create a ZIP file that contains the stream_manager folder, which contains the source code of the
Stream Manager SDK for Python. You can provide this ZIP file as a component artifact that the AWS
IoT Greengrass Core software unzips when it installs your component. Do the following:
a. Open the folder that contains the repository that you cloned or downloaded in the previous
step.
cd aws-greengrass-stream-manager-sdk-python
b. Zip the stream_manager folder into a ZIP file named stream_manager_sdk.zip.
Linux or Unix
zip -rv stream_manager_sdk.zip stream_manager
Windows Command Prompt (CMD)
tar -acvf stream_manager_sdk.zip stream_manager
PowerShell
Compress-Archive stream_manager stream_manager_sdk.zip
c. Verify that the stream_manager_sdk.zip file contains the stream_manager folder and its
contents. Run the following command to list the contents of the ZIP file.
686
AWS IoT Greengrass Developer Guide, Version 2
Define component recipes that use stream manager
Linux or Unix
unzip -l stream_manager_sdk.zip
Windows Command Prompt (CMD)
tar -tf stream_manager_sdk.zip
The output should look similar to the following.
Archive: aws-greengrass-stream-manager-sdk-python/stream_manager.zip
Length Date Time Name
--------- ---------- ----- ----
0 02-24-2021 20:45 stream_manager/
913 02-24-2021 20:45 stream_manager/__init__.py
9719 02-24-2021 20:45 stream_manager/utilinternal.py
1412 02-24-2021 20:45 stream_manager/exceptions.py
1004 02-24-2021 20:45 stream_manager/util.py
0 02-24-2021 20:45 stream_manager/data/
254463 02-24-2021 20:45 stream_manager/data/__init__.py
26515 02-24-2021 20:45 stream_manager/streammanagerclient.py
--------- -------
294026 8 files
3. Copy the Stream Manager SDK artifacts to your component's artifacts folder. In addition to the
Stream Manager SDK ZIP file, your component uses the SDK's requirements.txt file to install the
dependencies of the Stream Manager SDK. Replace ~/greengrass-components with the path to
the folder that you use for local development.
Linux or Unix
cp {stream_manager_sdk.zip,requirements.txt} ~/greengrass-components/artifacts/
com.example.StreamManagerS3Python/1.0.0/
Windows Command Prompt (CMD)
robocopy . %USERPROFILE%\greengrass-components\artifacts
\com.example.StreamManagerS3Python\1.0.0 stream_manager_sdk.zip
robocopy . %USERPROFILE%\greengrass-components\artifacts
\com.example.StreamManagerS3Python\1.0.0 requirements.txt
PowerShell
cp .\stream_manager_sdk.zip,.\requirements.txt ~\greengrass-components\artifacts
\com.example.StreamManagerS3Python\1.0.0\
4. Create your component recipe. In the recipe, do the following:
a. Define stream_manager_sdk.zip and requirements.txt as artifacts.
b. Define your Python application as an artifact.
c. In the install lifecycle, install the Stream Manager SDK requirements from requirements.txt.
d. In the run lifecycle, append the Stream Manager SDK to PYTHONPATH, and run your Python
application.
687
AWS IoT Greengrass Developer Guide, Version 2
Define component recipes that use stream manager
Your component recipe might look like the following example. This component runs the
stream_manager_s3.py example.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.StreamManagerS3Python",
"ComponentVersion": "1.0.0",
"ComponentDescription": "Uses stream manager to upload a file to an S3 bucket.",
"ComponentPublisher": "Amazon",
"ComponentDependencies": {
"aws.greengrass.StreamManager": {
"VersionRequirement": "^2.0.0"
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"Install": "pip3 install --user -r {artifacts:path}/requirements.txt",
"Run": "export PYTHONPATH=$PYTHONPATH:{artifacts:decompressedPath}/
stream_manager_sdk; python3 {artifacts:path}/stream_manager_s3.py"
},
"Artifacts": [
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.StreamManagerS3Python/1.0.0/stream_manager_sdk.zip",
"Unarchive": "ZIP"
},
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.StreamManagerS3Python/1.0.0/stream_manager_s3.py"
},
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.StreamManagerS3Python/1.0.0/requirements.txt"
}
]
},
{
"Platform": {
"os": "windows"
},
"Lifecycle": {
"Install": "pip3 install --user -r {artifacts:path}/requirements.txt",
"Run": "set PYTHONPATH=\"%PYTHONPATH%;{artifacts:decompressedPath}/
stream_manager_sdk\" & py -3 {artifacts:path}/stream_manager_s3.py"
},
"Artifacts": [
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.StreamManagerS3Python/1.0.0/stream_manager_sdk.zip",
"Unarchive": "ZIP"
},
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.StreamManagerS3Python/1.0.0/stream_manager_s3.py"
},
{
688
AWS IoT Greengrass Developer Guide, Version 2
Define component recipes that use stream manager
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.StreamManagerS3Python/1.0.0/requirements.txt"
}
]
}
]
}
YAML
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.StreamManagerS3Python
ComponentVersion: 1.0.0
ComponentDescription: Uses stream manager to upload a file to an S3 bucket.
ComponentPublisher: Amazon
ComponentDependencies:
aws.greengrass.StreamManager:
VersionRequirement: "^2.0.0"
Manifests:
- Platform:
os: linux
Lifecycle:
Install: pip3 install --user -r {artifacts:path}/requirements.txt
Run: |
export PYTHONPATH=$PYTHONPATH:{artifacts:decompressedPath}/
stream_manager_sdk
python3 {artifacts:path}/stream_manager_s3.py
Artifacts:
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.StreamManagerS3Python/1.0.0/stream_manager_sdk.zip
Unarchive: ZIP
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.StreamManagerS3Python/1.0.0/stream_manager_s3.py
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.StreamManagerS3Python/1.0.0/requirements.txt
- Platform:
os: windows
Lifecycle:
Install: pip3 install --user -r {artifacts:path}/requirements.txt
Run: |
set PYTHONPATH="%PYTHONPATH%;{artifacts:decompressedPath}/
stream_manager_sdk"
py -3 {artifacts:path}/stream_manager_s3.py
Artifacts:
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.StreamManagerS3Python/1.0.0/stream_manager_sdk.zip
Unarchive: ZIP
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.StreamManagerS3Python/1.0.0/stream_manager_s3.py
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.StreamManagerS3Python/1.0.0/requirements.txt
For more information about how to develop and test components, see Create AWS IoT Greengrass
components (p. 442).
Use the Stream Manager SDK for JavaScript
The Stream Manager SDK for JavaScript is available as source code that you can include in your
component. Create a ZIP file of the Stream Manager SDK, define the ZIP file as a component artifact, and
install the SDK in the component lifecycle.
689
AWS IoT Greengrass Developer Guide, Version 2
Define component recipes that use stream manager
To use the Stream Manager SDK for JavaScript
1. Clone or download the aws-greengrass-stream-manager-sdk-js repository.
git clone git@github.com:aws-greengrass/aws-greengrass-stream-manager-sdk-js.git
2. Create a ZIP file that contains the aws-greengrass-stream-manager-sdk folder, which
contains the source code of the Stream Manager SDK for JavaScript. You can provide this ZIP file
as a component artifact that the AWS IoT Greengrass Core software unzips when it installs your
component. Do the following:
a. Open the folder that contains the repository that you cloned or downloaded in the previous
step.
cd aws-greengrass-stream-manager-sdk-js
b. Zip the aws-greengrass-stream-manager-sdk folder into a ZIP file named stream-
manager-sdk.zip.
Linux or Unix
zip -rv stream-manager-sdk.zip aws-greengrass-stream-manager-sdk
Windows Command Prompt (CMD)
tar -acvf stream-manager-sdk.zip aws-greengrass-stream-manager-sdk
PowerShell
Compress-Archive aws-greengrass-stream-manager-sdk stream-manager-sdk.zip
c. Verify that the stream-manager-sdk.zip file contains the aws-greengrass-stream-
manager-sdk folder and its contents. Run the following command to list the contents of the
ZIP file.
Linux or Unix
unzip -l stream-manager-sdk.zip
Windows Command Prompt (CMD)
tar -tf stream-manager-sdk.zip
The output should look similar to the following.
Archive: stream-manager-sdk.zip
Length Date Time Name
--------- ---------- ----- ----
0 02-24-2021 22:36 aws-greengrass-stream-manager-sdk/
369 02-24-2021 22:36 aws-greengrass-stream-manager-sdk/package.json
1017 02-24-2021 22:36 aws-greengrass-stream-manager-sdk/util.js
8374 02-24-2021 22:36 aws-greengrass-stream-manager-sdk/utilInternal.js
1937 02-24-2021 22:36 aws-greengrass-stream-manager-sdk/exceptions.js
0 02-24-2021 22:36 aws-greengrass-stream-manager-sdk/data/
353343 02-24-2021 22:36 aws-greengrass-stream-manager-sdk/data/index.js
22599 02-24-2021 22:36 aws-greengrass-stream-manager-sdk/client.js
690
AWS IoT Greengrass Developer Guide, Version 2
Define component recipes that use stream manager
216 02-24-2021 22:36 aws-greengrass-stream-manager-sdk/index.js
--------- -------
387855 9 files
3. Copy the Stream Manager SDK artifact to your component's artifacts folder. Replace ~/
greengrass-components with the path to the folder that you use for local development.
Linux or Unix
cp stream-manager-sdk.zip ~/greengrass-components/artifacts/
com.example.StreamManagerS3JS/1.0.0/
Windows Command Prompt (CMD)
robocopy . %USERPROFILE%\greengrass-components\artifacts
\com.example.StreamManagerS3JS\1.0.0 stream-manager-sdk.zip
PowerShell
cp .\stream-manager-sdk.zip ~\greengrass-components\artifacts
\com.example.StreamManagerS3JS\1.0.0\
4. Create your component recipe. In the recipe, do the following:
a. Define stream-manager-sdk.zip as an artifact.
b. Define your JavaScript application as an artifact.
c. In the install lifecycle, install the Stream Manager SDK from the stream-manager-sdk.zip
artifact. This npm install command creates a node_modules folder that contains the Stream
Manager SDK and its dependencies.
d. In the run lifecycle, append the node_modules folder to NODE_PATH, and run your JavaScript
application.
Your component recipe might look like the following example. This component runs the
StreamManagerS3 example.
JSON
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.StreamManagerS3JS",
"ComponentVersion": "1.0.0",
"ComponentDescription": "Uses stream manager to upload a file to an S3 bucket.",
"ComponentPublisher": "Amazon",
"ComponentDependencies": {
"aws.greengrass.StreamManager": {
"VersionRequirement": "^2.0.0"
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"Install": "npm install {artifacts:decompressedPath}/stream-manager-sdk/
aws-greengrass-stream-manager-sdk",
"Run": "export NODE_PATH=$NODE_PATH:{work:path}/node_modules; node
{artifacts:path}/index.js"
691
AWS IoT Greengrass Developer Guide, Version 2
Define component recipes that use stream manager
},
"Artifacts": [
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.StreamManagerS3JS/1.0.0/stream-manager-sdk.zip",
"Unarchive": "ZIP"
},
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.StreamManagerS3JS/1.0.0/index.js"
}
]
},
{
"Platform": {
"os": "windows"
},
"Lifecycle": {
"Install": "npm install {artifacts:decompressedPath}/stream-manager-sdk/
aws-greengrass-stream-manager-sdk",
"Run": "set NODE_PATH=\"%NODE_PATH%;{work:path}/node_modules\" & node
{artifacts:path}/index.js"
},
"Artifacts": [
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.StreamManagerS3JS/1.0.0/stream-manager-sdk.zip",
"Unarchive": "ZIP"
},
{
"URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/
com.example.StreamManagerS3JS/1.0.0/index.js"
}
]
}
]
}
YAML
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.StreamManagerS3JS
ComponentVersion: 1.0.0
ComponentDescription: Uses stream manager to upload a file to an S3 bucket.
ComponentPublisher: Amazon
ComponentDependencies:
aws.greengrass.StreamManager:
VersionRequirement: "^2.0.0"
Manifests:
- Platform:
os: linux
Lifecycle:
Install: npm install {artifacts:decompressedPath}/stream-manager-sdk/aws-
greengrass-stream-manager-sdk
Run: |
export NODE_PATH=$NODE_PATH:{work:path}/node_modules
node {artifacts:path}/index.js
Artifacts:
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.StreamManagerS3JS/1.0.0/
stream-manager-sdk.zip
Unarchive: ZIP
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.StreamManagerS3JS/1.0.0/
index.js
692
AWS IoT Greengrass Developer Guide, Version 2
Connect to stream manager in application code
- Platform:
os: windows
Lifecycle:
Install: npm install {artifacts:decompressedPath}/stream-manager-sdk/aws-
greengrass-stream-manager-sdk
Run: |
set NODE_PATH="%NODE_PATH%;{work:path}/node_modules"
node {artifacts:path}/index.js
Artifacts:
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.StreamManagerS3JS/1.0.0/
stream-manager-sdk.zip
Unarchive: ZIP
- URI: s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.StreamManagerS3JS/1.0.0/
index.js
For more information about how to develop and test components, see Create AWS IoT Greengrass
components (p. 442).
Connect to stream manager in application code
To connect to stream manager in your application, create an instance of StreamManagerClient from
the Stream Manager SDK. This client connects to the stream manager component on its default port
8088, or the port that you specify. For more information about how to use StreamManagerClient
after you create an instance, see Use StreamManagerClient to work with streams (p. 695).
Example Example: Connect to stream manager with default port
Java
import com.amazonaws.greengrass.streammanager.client.StreamManagerClient;
public class MyStreamManagerComponent {
void connectToStreamManagerWithDefaultPort() {
StreamManagerClient client = StreamManagerClientFactory.standard().build();
// Use the client.
}
}
Python
from stream_manager import (
StreamManagerClient
)
def connect_to_stream_manager_with_default_port():
client = StreamManagerClient()
# Use the client.
JavaScript
const {
StreamManagerClient
} = require('aws-greengrass-stream-manager-sdk');
function connectToStreamManagerWithDefaultPort() {
693
AWS IoT Greengrass Developer Guide, Version 2
Connect to stream manager in application code
const client = new StreamManagerClient();
// Use the client.
}
Example Example: Connect to stream manager with non-default port
If you configure stream manager with a port other than the default, you must use interprocess
communication (p. 545) to retrieve the port from the component configuration.
Note
The port configuration parameter contains the value that you specify in
STREAM_MANAGER_SERVER_PORT when you deploy stream manager.
Java
void connectToStreamManagerWithCustomPort() {
EventStreamRPCConnection eventStreamRpcConnection =
IPCUtils.getEventStreamRpcConnection();
GreengrassCoreIPCClient greengrassCoreIPCClient = new
GreengrassCoreIPCClient(eventStreamRpcConnection);
List<String> keyPath = new ArrayList<>();
keyPath.add("port");
GetConfigurationRequest request = new GetConfigurationRequest();
request.setComponentName("aws.greengrass.StreamManager");
request.setKeyPath(keyPath);
GetConfigurationResponse response =
greengrassCoreIPCClient.getConfiguration(request,
Optional.empty()).getResponse().get();
String port = response.getValue().get("port").toString();
System.out.print("Stream Manager is running on port: " + port);
final StreamManagerClientConfig config = StreamManagerClientConfig.builder()
.serverInfo(StreamManagerServerInfo.builder().port(Integer.parseInt(port)).build()).build();
StreamManagerClient client =
StreamManagerClientFactory.standard().withClientConfig(config).build();
// Use the client.
}
Python
import awsiot.greengrasscoreipc
from awsiot.greengrasscoreipc.model import (
GetConfigurationRequest
)
from stream_manager import (
StreamManagerClient
)
TIMEOUT = 10
def connect_to_stream_manager_with_custom_port():
# Use IPC to get the port from the stream manager component configuration.
ipc_client = awsiot.greengrasscoreipc.connect()
request = GetConfigurationRequest()
request.component_name = "aws.greengrass.StreamManager"
request.key_path = ["port"]
operation = ipc_client.new_get_configuration()
694
AWS IoT Greengrass Developer Guide, Version 2
Use StreamManagerClient to work with streams
operation.activate(request)
futureResponse = operation.get_response()
response = futureResponse.result(TIMEOUT)
stream_manager_port = str(response.value["port"])
# Use port to create a stream manager client.
stream_client = StreamManagerClient(port=stream_manager_port)
# Use the client.
Use StreamManagerClient to work with streams
User-defined Greengrass components that run on the Greengrass core device can use the
StreamManagerClient object in the Stream Manager SDK to create streams in stream
manager (p. 682) and then interact with the streams. When a component creates a stream, it defines
the AWS Cloud destinations, prioritization, and other export and data retention policies for the stream.
To send data to stream manager, components append the data to the stream. If an export destination is
defined for the stream, stream manager exports the stream automatically.
Note
Typically, clients of stream manager are user-defined Greengrass components. If your business
case requires it, you can also allow non-component processes running on the Greengrass core
(for example, a Docker container) to interact with stream manager. For more information, see
the section called “Client authentication” (p. 684).
The snippets in this topic show you how clients call StreamManagerClient methods to work with
streams. For implementation details about the methods and their arguments, use the links to the SDK
reference listed after each snippet.
If you use stream manager in a Lambda function, your Lambda function should instantiate
StreamManagerClient outside of the function handler. If instantiated in the handler, the function
creates a client and connection to stream manager every time that it's invoked.
Note
If you do instantiate StreamManagerClient in the handler, you must explicitly call the
close() method when the client completes its work. Otherwise, the client keeps the
connection open and another thread running until the script exits.
StreamManagerClient supports the following operations:
• the section called “Create message stream” (p. 695)
• the section called “Append message” (p. 698)
• the section called “Read messages” (p. 702)
• the section called “List streams” (p. 704)
• the section called “Describe message stream” (p. 705)
• the section called “Update message stream” (p. 706)
• the section called “Delete message stream” (p. 709)
Create message stream
To create a stream, a user-defined Greengrass component calls the create method and passes in a
MessageStreamDefinition object. This object specifies the unique name for the stream and defines
how stream manager should handle new data when the maximum stream size is reached. You can use
MessageStreamDefinition and its data types (such as ExportDefinition, StrategyOnFull, and
Persistence) to define other stream properties. These include:
695
AWS IoT Greengrass Developer Guide, Version 2
Create message stream
• The target AWS IoT Analytics, Kinesis Data Streams, AWS IoT SiteWise, and Amazon S3 destinations for
automatic exports. For more information, see the section called “Export configurations for supported
cloud destinations” (p. 710).
• Export priority. Stream manager exports higher priority streams before lower priority streams.
• Maximum batch size and batch interval for AWS IoT Analytics, Kinesis Data Streams, and AWS IoT
SiteWise destinations. Stream manager exports messages when either condition is met.
• Time-to-live (TTL). The amount of time to guarantee that the stream data is available for processing.
You should make sure that the data can be consumed within this time period. This is not a deletion
policy. The data might not be deleted immediately after TTL period.
• Stream persistence. Choose to save streams to the file system to persist data across core restarts or
save streams in memory.
• Starting sequence number. Specify the sequence number of the message to use as the starting
message in the export.
For more information about MessageStreamDefinition, see the SDK reference for your target
language:
• MessageStreamDefinition in the Java SDK
• MessageStreamDefinition in the Node.js SDK
• MessageStreamDefinition in the Python SDK
Note
StreamManagerClient also provides a target destination you can use to export streams to an
HTTP server. This target is intended for testing purposes only. It is not stable or supported for
use in production environments.
After a stream is created, your Greengrass components can append messages (p. 698) to the stream
to send data for export and read messages (p. 702) from the stream for local processing. The number
of streams that you create depends on your hardware capabilities and business case. One strategy is
to create a stream for each target channel in AWS IoT Analytics or Kinesis data stream, though you can
define multiple targets for a stream. A stream has a durable lifespan.
Requirements
This operation has the following requirements:
• Minimum Stream Manager SDK version: Python: 1.1.0 | Java: 1.1.0 | Node.js: 1.1.0
Examples
The following snippet creates a stream named StreamName. It defines stream properties in the
MessageStreamDefinition and subordinate data types.
Python
client = StreamManagerClient()
try:
client.create_message_stream(MessageStreamDefinition(
name="StreamName", # Required.
max_size=268435456, # Default is 256 MB.
stream_segment_size=16777216, # Default is 16 MB.
time_to_live_millis=None, # By default, no TTL is enabled.
strategy_on_full=StrategyOnFull.OverwriteOldestData, # Required.
696
AWS IoT Greengrass Developer Guide, Version 2
Create message stream
persistence=Persistence.File, # Default is File.
flush_on_write=False, # Default is false.
export_definition=ExportDefinition( # Optional. Choose where/how the stream
is exported to the AWS Cloud.
kinesis=None,
iot_analytics=None,
iot_sitewise=None,
s3_task_executor=None
)
))
except StreamManagerException:
pass
# Properly handle errors.
except ConnectionError or asyncio.TimeoutError:
pass
# Properly handle errors.
Python SDK reference: create_message_stream | MessageStreamDefinition
Java
try (final StreamManagerClient client = StreamManagerClientFactory.standard().build())
{
client.createMessageStream(
new MessageStreamDefinition()
.withName("StreamName") // Required.
.withMaxSize(268435456L) // Default is 256 MB.
.withStreamSegmentSize(16777216L) // Default is 16 MB.
.withTimeToLiveMillis(null) // By default, no TTL is enabled.
.withStrategyOnFull(StrategyOnFull.OverwriteOldestData) //
Required.
.withPersistence(Persistence.File) // Default is File.
.withFlushOnWrite(false) // Default is false.
.withExportDefinition( // Optional. Choose where/how the stream
is exported to the AWS Cloud.
new ExportDefinition()
.withKinesis(null)
.withIotAnalytics(null)
.withIotSiteWise(null)
.withS3(null)
)
);
} catch (StreamManagerException e) {
// Properly handle exception.
}
Java SDK reference: createMessageStream | MessageStreamDefinition
Node.js
const client = new StreamManagerClient();
client.onConnected(async () => {
try {
await client.createMessageStream(
new MessageStreamDefinition()
.withName("StreamName") // Required.
.withMaxSize(268435456) // Default is 256 MB.
.withStreamSegmentSize(16777216) // Default is 16 MB.
.withTimeToLiveMillis(null) // By default, no TTL is enabled.
.withStrategyOnFull(StrategyOnFull.OverwriteOldestData) // Required.
.withPersistence(Persistence.File) // Default is File.
.withFlushOnWrite(false) // Default is false.
.withExportDefinition( // Optional. Choose where/how the stream is exported to
the AWS Cloud.
697
AWS IoT Greengrass Developer Guide, Version 2
Append message
new ExportDefinition()
.withKinesis(null)
.withIotAnalytics(null)
.withIotSiteWise(null)
.withS3(null)
)
);
} catch (e) {
// Properly handle errors.
}
});
client.onError((err) => {
// Properly handle connection errors.
// This is called only when the connection to the StreamManager server fails.
});
Node.js SDK reference: createMessageStream | MessageStreamDefinition
For more information about configuring export destinations, see the section called “Export
configurations for supported cloud destinations” (p. 710).
Append message
To send data to stream manager for export, your Greengrass components append the data to the target
stream. The export destination determines the data type to pass to this method.
Requirements
This operation has the following requirements:
• Minimum Stream Manager SDK version: Python: 1.1.0 | Java: 1.1.0 | Node.js: 1.1.0
Examples
AWS IoT Analytics or Kinesis Data Streams export destinations
The following snippet appends a message to the stream named StreamName. For AWS IoT Analytics or
Kinesis Data Streams destinations, your Greengrass components append a blob of data.
This snippet has the following requirements:
• Minimum Stream Manager SDK version: Python: 1.1.0 | Java: 1.1.0 | Node.js: 1.1.0
Python
client = StreamManagerClient()
try:
sequence_number = client.append_message(stream_name="StreamName", data=b'Arbitrary
bytes data')
except StreamManagerException:
pass
# Properly handle errors.
except ConnectionError or asyncio.TimeoutError:
pass
# Properly handle errors.
698
AWS IoT Greengrass Developer Guide, Version 2
Append message
Python SDK reference: append_message
Java
try (final StreamManagerClient client = StreamManagerClientFactory.standard().build())
{
long sequenceNumber = client.appendMessage("StreamName", "Arbitrary byte
array".getBytes());
} catch (StreamManagerException e) {
// Properly handle exception.
}
Java SDK reference: appendMessage
Node.js
const client = new StreamManagerClient();
client.onConnected(async () => {
try {
const sequenceNumber = await client.appendMessage("StreamName",
Buffer.from("Arbitrary byte array"));
} catch (e) {
// Properly handle errors.
}
});
client.onError((err) => {
// Properly handle connection errors.
// This is called only when the connection to the StreamManager server fails.
});
Node.js SDK reference: appendMessage
AWS IoT SiteWise export destinations
The following snippet appends a message to the stream named StreamName. For AWS IoT SiteWise
destinations, your Greengrass components append a serialized PutAssetPropertyValueEntry object.
For more information, see the section called “Exporting to AWS IoT SiteWise” (p. 714).
Note
When you send data to AWS IoT SiteWise, your data must meet the requirements
of the BatchPutAssetPropertyValue action. For more information, see
BatchPutAssetPropertyValue in the AWS IoT SiteWise API Reference.
This snippet has the following requirements:
• Minimum Stream Manager SDK version: Python: 1.1.0 | Java: 1.1.0 | Node.js: 1.1.0
Python
client = StreamManagerClient()
try:
# SiteWise requires unique timestamps in all messages and also needs timestamps not
earlier
# than 10 minutes in the past. Add some randomness to time and offset.
# Note: To create a new asset property data, you should use the classes defined in
the
# greengrasssdk.stream_manager module.
time_in_nanos = TimeInNanos(
699
AWS IoT Greengrass Developer Guide, Version 2
Append message
time_in_seconds=calendar.timegm(time.gmtime()) - random.randint(0, 60),
offset_in_nanos=random.randint(0, 10000)
)
variant = Variant(double_value=random.random())
asset = [AssetPropertyValue(value=variant, quality=Quality.GOOD,
timestamp=time_in_nanos)]
putAssetPropertyValueEntry = PutAssetPropertyValueEntry(entry_id=str(uuid.uuid4()),
property_alias="PropertyAlias", property_values=asset)
sequence_number = client.append_message(stream_name="StreamName",
Util.validate_and_serialize_to_json_bytes(putAssetPropertyValueEntry))
except StreamManagerException:
pass
# Properly handle errors.
except ConnectionError or asyncio.TimeoutError:
pass
# Properly handle errors.
Python SDK reference: append_message | PutAssetPropertyValueEntry
Java
try (final StreamManagerClient client =
GreengrassClientBuilder.streamManagerClient().build()) {
Random rand = new Random();
// Note: To create a new asset property data, you should use the classes defined in
the
// com.amazonaws.greengrass.streammanager.model.sitewise package.
List<AssetPropertyValue> entries = new ArrayList<>() ;
// IoTSiteWise requires unique timestamps in all messages and also needs timestamps
not earlier
// than 10 minutes in the past. Add some randomness to time and offset.
final int maxTimeRandomness = 60;
final int maxOffsetRandomness = 10000;
double randomValue = rand.nextDouble();
TimeInNanos timestamp = new TimeInNanos()
.withTimeInSeconds(Instant.now().getEpochSecond() -
rand.nextInt(maxTimeRandomness))
.withOffsetInNanos((long) (rand.nextInt(maxOffsetRandomness)));
AssetPropertyValue entry = new AssetPropertyValue()
.withValue(new Variant().withDoubleValue(randomValue))
.withQuality(Quality.GOOD)
.withTimestamp(timestamp);
entries.add(entry);
PutAssetPropertyValueEntry putAssetPropertyValueEntry = new
PutAssetPropertyValueEntry()
.withEntryId(UUID.randomUUID().toString())
.withPropertyAlias("PropertyAlias")
.withPropertyValues(entries);
long sequenceNumber = client.appendMessage("StreamName",
ValidateAndSerialize.validateAndSerializeToJsonBytes(putAssetPropertyValueEntry));
} catch (StreamManagerException e) {
// Properly handle exception.
}
Java SDK reference: appendMessage | PutAssetPropertyValueEntry
Node.js
const client = new StreamManagerClient();
client.onConnected(async () => {
try {
const maxTimeRandomness = 60;
700
AWS IoT Greengrass Developer Guide, Version 2
Append message
const maxOffsetRandomness = 10000;
const randomValue = Math.random();
// Note: To create a new asset property data, you should use the classes
defined in the
// aws-greengrass-core-sdk StreamManager module.
const timestamp = new TimeInNanos()
.withTimeInSeconds(Math.round(Date.now() / 1000) - Math.floor(Math.random()
- maxTimeRandomness))
.withOffsetInNanos(Math.floor(Math.random() * maxOffsetRandomness));
const entry = new AssetPropertyValue()
.withValue(new Variant().withDoubleValue(randomValue))
.withQuality(Quality.GOOD)
.withTimestamp(timestamp);
const putAssetPropertyValueEntry = new PutAssetPropertyValueEntry()
.withEntryId(`${ENTRY_ID_PREFIX}${i}`)
.withPropertyAlias("PropertyAlias")
.withPropertyValues([entry]);
const sequenceNumber = await client.appendMessage("StreamName",
util.validateAndSerializeToJsonBytes(putAssetPropertyValueEntry));
} catch (e) {
// Properly handle errors.
}
});
client.onError((err) => {
// Properly handle connection errors.
// This is called only when the connection to the StreamManager server fails.
});
Node.js SDK reference: appendMessage | PutAssetPropertyValueEntry
Amazon S3 export destinations
The following snippet appends an export task to the stream named StreamName. For Amazon S3
destinations, your Greengrass components append a serialized S3ExportTaskDefinition object that
contains information about the source input file and target Amazon S3 object. If the specified object
doesn't exist, Stream Manager creates it for you. For more information, see the section called “Exporting
to Amazon S3” (p. 716).
This snippet has the following requirements:
• Minimum Stream Manager SDK version: Python: 1.1.0 | Java: 1.1.0 | Node.js: 1.1.0
Python
client = StreamManagerClient()
try:
# Append an Amazon S3 Task definition and print the sequence number.
s3_export_task_definition = S3ExportTaskDefinition(input_url="URLToFile",
bucket="BucketName", key="KeyName")
sequence_number = client.append_message(stream_name="StreamName",
Util.validate_and_serialize_to_json_bytes(s3_export_task_definition))
except StreamManagerException:
pass
# Properly handle errors.
except ConnectionError or asyncio.TimeoutError:
pass
# Properly handle errors.
Python SDK reference: append_message | S3ExportTaskDefinition
701
AWS IoT Greengrass Developer Guide, Version 2
Read messages
Java
try (final StreamManagerClient client =
GreengrassClientBuilder.streamManagerClient().build()) {
// Append an Amazon S3 export task definition and print the sequence number.
S3ExportTaskDefinition s3ExportTaskDefinition = new S3ExportTaskDefinition()
.withBucket("BucketName")
.withKey("KeyName")
.withInputUrl("URLToFile");
long sequenceNumber = client.appendMessage("StreamName",
ValidateAndSerialize.validateAndSerializeToJsonBytes(s3ExportTaskDefinition));
} catch (StreamManagerException e) {
// Properly handle exception.
}
Java SDK reference: appendMessage | S3ExportTaskDefinition
Node.js
const client = new StreamManagerClient();
client.onConnected(async () => {
try {
// Append an Amazon S3 export task definition and print the sequence number.
const taskDefinition = new S3ExportTaskDefinition()
.withBucket("BucketName")
.withKey("KeyName")
.withInputUrl("URLToFile");
const sequenceNumber = await client.appendMessage("StreamName",
util.validateAndSerializeToJsonBytes(taskDefinition)));
} catch (e) {
// Properly handle errors.
}
});
client.onError((err) => {
// Properly handle connection errors.
// This is called only when the connection to the StreamManager server fails.
});
Node.js SDK reference: appendMessage | S3ExportTaskDefinition
Read messages
Read messages from a stream.
Requirements
This operation has the following requirements:
• Minimum Stream Manager SDK version: Python: 1.1.0 | Java: 1.1.0 | Node.js: 1.1.0
Examples
The following snippet reads messages from the stream named StreamName. The read method takes an
optional ReadMessagesOptions object that specifies the sequence number to start reading from, the
minimum and maximum numbers to read, and a timeout for reading messages.
Python
client = StreamManagerClient()
702
AWS IoT Greengrass Developer Guide, Version 2
Read messages
try:
message_list = client.read_messages(
stream_name="StreamName",
# By default, if no options are specified, it tries to read one message from
the beginning of the stream.
options=ReadMessagesOptions(
desired_start_sequence_number=100,
# Try to read from sequence number 100 or greater. By default, this is 0.
min_message_count=10,
# Try to read 10 messages. If 10 messages are not available, then
NotEnoughMessagesException is raised. By default, this is 1.
max_message_count=100, # Accept up to 100 messages. By default this is
1.
read_timeout_millis=5000
# Try to wait at most 5 seconds for the min_messsage_count to be fulfilled.
By default, this is 0, which immediately returns the messages or an exception.
)
)
except StreamManagerException:
pass
# Properly handle errors.
except ConnectionError or asyncio.TimeoutError:
pass
# Properly handle errors.
Python SDK reference: read_messages | ReadMessagesOptions
Java
try (final StreamManagerClient client = StreamManagerClientFactory.standard().build())
{
List<Message> messages = client.readMessages("StreamName",
// By default, if no options are specified, it tries to read one message
from the beginning of the stream.
new ReadMessagesOptions()
// Try to read from sequence number 100 or greater. By default this
is 0.
.withDesiredStartSequenceNumber(100L)
// Try to read 10 messages. If 10 messages are not available, then
NotEnoughMessagesException is raised. By default, this is 1.
.withMinMessageCount(10L)
// Accept up to 100 messages. By default this is 1.
.withMaxMessageCount(100L)
// Try to wait at most 5 seconds for the min_messsage_count to
be fulfilled. By default, this is 0, which immediately returns the messages or an
exception.
.withReadTimeoutMillis(Duration.ofSeconds(5L).toMillis())
);
} catch (StreamManagerException e) {
// Properly handle exception.
}
Java SDK reference: readMessages | ReadMessagesOptions
Node.js
const client = new StreamManagerClient();
client.onConnected(async () => {
try {
const messages = await client.readMessages("StreamName",
// By default, if no options are specified, it tries to read one message
from the beginning of the stream.
new ReadMessagesOptions()
703
AWS IoT Greengrass Developer Guide, Version 2
List streams
// Try to read from sequence number 100 or greater. By default this is
0.
.withDesiredStartSequenceNumber(100)
// Try to read 10 messages. If 10 messages are not available, then
NotEnoughMessagesException is thrown. By default, this is 1.
.withMinMessageCount(10)
// Accept up to 100 messages. By default this is 1.
.withMaxMessageCount(100)
// Try to wait at most 5 seconds for the minMessageCount to be
fulfilled. By default, this is 0, which immediately returns the messages or an
exception.
.withReadTimeoutMillis(5 * 1000)
);
} catch (e) {
// Properly handle errors.
}
});
client.onError((err) => {
// Properly handle connection errors.
// This is called only when the connection to the StreamManager server fails.
});
Node.js SDK reference: readMessages | ReadMessagesOptions
List streams
Get the list of streams in stream manager.
Requirements
This operation has the following requirements:
• Minimum Stream Manager SDK version: Python: 1.1.0 | Java: 1.1.0 | Node.js: 1.1.0
Examples
The following snippet gets a list of the streams (by name) in stream manager.
Python
client = StreamManagerClient()
try:
stream_names = client.list_streams()
except StreamManagerException:
pass
# Properly handle errors.
except ConnectionError or asyncio.TimeoutError:
pass
# Properly handle errors.
Python SDK reference: list_streams
Java
try (final StreamManagerClient client = StreamManagerClientFactory.standard().build())
{
List<String> streamNames = client.listStreams();
} catch (StreamManagerException e) {
704
AWS IoT Greengrass Developer Guide, Version 2
Describe message stream
// Properly handle exception.
}
Java SDK reference: listStreams
Node.js
const client = new StreamManagerClient();
client.onConnected(async () => {
try {
const streams = await client.listStreams();
} catch (e) {
// Properly handle errors.
}
});
client.onError((err) => {
// Properly handle connection errors.
// This is called only when the connection to the StreamManager server fails.
});
Node.js SDK reference: listStreams
Describe message stream
Get metadata about a stream, including the stream definition, size, and export status.
Requirements
This operation has the following requirements:
• Minimum Stream Manager SDK version: Python: 1.1.0 | Java: 1.1.0 | Node.js: 1.1.0
Examples
The following snippet gets metadata about the stream named StreamName, including the stream's
definition, size, and exporter statuses.
Python
client = StreamManagerClient()
try:
stream_description = client.describe_message_stream(stream_name="StreamName")
if stream_description.export_statuses[0].error_message:
# The last export of export destination 0 failed with some error
# Here is the last sequence number that was successfully exported
stream_description.export_statuses[0].last_exported_sequence_number
if (stream_description.storage_status.newest_sequence_number >
stream_description.export_statuses[0].last_exported_sequence_number):
pass
# The end of the stream is ahead of the last exported sequence number
except StreamManagerException:
pass
# Properly handle errors.
except ConnectionError or asyncio.TimeoutError:
pass
# Properly handle errors.
705
AWS IoT Greengrass Developer Guide, Version 2
Update message stream
Python SDK reference: describe_message_stream
Java
try (final StreamManagerClient client = StreamManagerClientFactory.standard().build())
{
MessageStreamInfo description = client.describeMessageStream("StreamName");
String lastErrorMessage = description.getExportStatuses().get(0).getErrorMessage();
if (lastErrorMessage != null && !lastErrorMessage.equals("")) {
// The last export of export destination 0 failed with some error.
// Here is the last sequence number that was successfully exported.
description.getExportStatuses().get(0).getLastExportedSequenceNumber();
}
if (description.getStorageStatus().getNewestSequenceNumber() >
description.getExportStatuses().get(0).getLastExportedSequenceNumber()) {
// The end of the stream is ahead of the last exported sequence number.
}
} catch (StreamManagerException e) {
// Properly handle exception.
}
Java SDK reference: describeMessageStream
Node.js
const client = new StreamManagerClient();
client.onConnected(async () => {
try {
const description = await client.describeMessageStream("StreamName");
const lastErrorMessage = description.exportStatuses[0].errorMessage;
if (lastErrorMessage) {
// The last export of export destination 0 failed with some error.
// Here is the last sequence number that was successfully exported.
description.exportStatuses[0].lastExportedSequenceNumber;
}
if (description.storageStatus.newestSequenceNumber >
description.exportStatuses[0].lastExportedSequenceNumber) {
// The end of the stream is ahead of the last exported sequence number.
}
} catch (e) {
// Properly handle errors.
}
});
client.onError((err) => {
// Properly handle connection errors.
// This is called only when the connection to the StreamManager server fails.
});
Node.js SDK reference: describeMessageStream
Update message stream
Update properties of an existing stream. You might want to update a stream if your requirements change
after the stream was created. For example:
• Add a new export configuration (p. 710) for an AWS Cloud destination.
• Increase the maximum size of a stream to change how data is exported or retained. For example, the
stream size in combination with your strategy on full settings might result in data being deleted or
rejected before stream manager can process it.
706
AWS IoT Greengrass Developer Guide, Version 2
Update message stream
• Pause and resume exports; for example, if export tasks are long running and you want to ration your
upload data.
Your Greengrass components follow this high-level process to update a stream:
1. Get the description of the stream. (p. 705)
2. Update the target properties on the corresponding MessageStreamDefinition and subordinate
objects.
3. Pass in the updated MessageStreamDefinition. Make sure to include the complete object
definitions for the updated stream. Undefined properties revert to the default values.
You can specify the sequence number of the message to use as the starting message in the export.
Requirements
This operation has the following requirements:
• Minimum Stream Manager SDK version: Python: 1.1.0 | Java: 1.1.0 | Node.js: 1.1.0
Examples
The following snippet updates the stream named StreamName. It updates multiple properties of a
stream that exports to Kinesis Data Streams.
Python
client = StreamManagerClient()
try:
message_stream_info = client.describe_message_stream(STREAM_NAME)
message_stream_info.definition.max_size=536870912
message_stream_info.definition.stream_segment_size=33554432
message_stream_info.definition.time_to_live_millis=3600000
message_stream_info.definition.strategy_on_full=StrategyOnFull.RejectNewData
message_stream_info.definition.persistence=Persistence.Memory
message_stream_info.definition.flush_on_write=False
message_stream_info.definition.export_definition.kinesis=
[KinesisConfig(
# Updating Export definition to add a Kinesis Stream configuration.
identifier=str(uuid.uuid4()), kinesis_stream_name=str(uuid.uuid4()))]
client.update_message_stream(message_stream_info.definition)
except StreamManagerException:
pass
# Properly handle errors.
except ConnectionError or asyncio.TimeoutError:
pass
# Properly handle errors.
Python SDK reference: updateMessageStream | MessageStreamDefinition
Java
try (final StreamManagerClient client =
GreengrassClientBuilder.streamManagerClient().build()) {
MessageStreamInfo messageStreamInfo = client.describeMessageStream(STREAM_NAME);
// Update the message stream with new values.
client.updateMessageStream(
707
AWS IoT Greengrass Developer Guide, Version 2
Update message stream
messageStreamInfo.getDefinition()
.withStrategyOnFull(StrategyOnFull.RejectNewData) // Required. Updating
Strategy on full to reject new data.
// Max Size update should be greater than initial Max Size defined in
Create Message Stream request
.withMaxSize(536870912L) // Update Max Size to 512 MB.
.withStreamSegmentSize(33554432L) // Update Segment Size to 32 MB.
.withFlushOnWrite(true) // Update flush on write to true.
.withPersistence(Persistence.Memory) // Update the persistence to Memory.
.withTimeToLiveMillis(3600000L) // Update TTL to 1 hour.
.withExportDefinition(
// Optional. Choose where/how the stream is exported to the AWS Cloud.
messageStreamInfo.getDefinition().getExportDefinition().
// Updating Export definition to add a Kinesis Stream
configuration.
.withKinesis(new ArrayList<KinesisConfig>() {{
add(new KinesisConfig()
.withIdentifier(EXPORT_IDENTIFIER)
.withKinesisStreamName("test"));
}})
);
} catch (StreamManagerException e) {
// Properly handle exception.
}
Java SDK reference: update_message_stream | MessageStreamDefinition
Node.js
const client = new StreamManagerClient();
client.onConnected(async () => {
try {
const messageStreamInfo = await c.describeMessageStream(STREAM_NAME);
await client.updateMessageStream(
messageStreamInfo.definition
// Max Size update should be greater than initial Max Size defined in
Create Message Stream request
.withMaxSize(536870912) // Default is 256 MB. Updating Max Size to
512 MB.
.withStreamSegmentSize(33554432) // Default is 16 MB. Updating
Segment Size to 32 MB.
.withTimeToLiveMillis(3600000) // By default, no TTL is enabled.
Update TTL to 1 hour.
.withStrategyOnFull(StrategyOnFull.RejectNewData) // Required.
Updating Strategy on full to reject new data.
.withPersistence(Persistence.Memory) // Default is File. Update the
persistence to Memory
.withFlushOnWrite(true) // Default is false. Updating to true.
.withExportDefinition(
// Optional. Choose where/how the stream is exported to the AWS
Cloud.
messageStreamInfo.definition.exportDefinition
// Updating Export definition to add a Kinesis Stream
configuration.
.withKinesis([new
KinesisConfig().withIdentifier(uuidv4()).withKinesisStreamName(uuidv4())])
)
);
} catch (e) {
// Properly handle errors.
}
});
client.onError((err) => {
// Properly handle connection errors.
// This is called only when the connection to the StreamManager server fails.
708
AWS IoT Greengrass Developer Guide, Version 2
Delete message stream
});
Node.js SDK reference: updateMessageStream | MessageStreamDefinition
Constraints for updating streams
The following constraints apply when updating streams. Unless noted in the following list, updates take
effect immediately.
• You can't update a stream's persistence. To change this behavior, delete the stream (p. 709) and
create a stream (p. 695) that defines the new persistence policy.
• You can update the maximum size of a stream only under the following conditions:
• The maximum size must be greater or equal to the current size of the stream. To find this
information, describe the stream (p. 705) and then check the storage status of the returned
MessageStreamInfo object.
• The maximum size must be greater than or equal to the stream's segment size.
• You can update the stream segment size to a value less than the maximum size of the stream. The
updated setting applies to new segments.
• Updates to the time to live (TTL) property apply to new append operations. If you decrease this value,
stream manager might also delete existing segments that exceed the TTL.
• Updates to the strategy on full property apply to new append operations. If you set the strategy to
overwrite the oldest data, stream manager might also overwrite existing segments based on the new
setting.
• Updates to the flush on write property apply to new messages.
• Updates to export configurations apply to new exports. The update request must include all export
configurations that you want to support. Otherwise, stream manager deletes them.
• When you update an export configuration, specify the identifier of the target export configuration.
• To add an export configuration, specify a unique identifier for the new export configuration.
• To delete an export configuration, omit the export configuration.
• To update (p. 706) the starting sequence number of an export configuration in a stream, you must
specify a value that's less than the latest sequence number. To find this information, describe the
stream (p. 705) and then check the storage status of the returned MessageStreamInfo object.
Delete message stream
Deletes a stream. When you delete a stream, all of the stored data for the stream is deleted from the
disk.
Requirements
This operation has the following requirements:
• Minimum Stream Manager SDK version: Python: 1.1.0 | Java: 1.1.0 | Node.js: 1.1.0
Examples
The following snippet deletes the stream named StreamName.
Python
client = StreamManagerClient()
709
AWS IoT Greengrass Developer Guide, Version 2
See also
try:
client.delete_message_stream(stream_name="StreamName")
except StreamManagerException:
pass
# Properly handle errors.
except ConnectionError or asyncio.TimeoutError:
pass
# Properly handle errors.
Python SDK reference: deleteMessageStream
Java
try (final StreamManagerClient client = StreamManagerClientFactory.standard().build())
{
client.deleteMessageStream("StreamName");
} catch (StreamManagerException e) {
// Properly handle exception.
}
Java SDK reference: delete_message_stream
Node.js
const client = new StreamManagerClient();
client.onConnected(async () => {
try {
await client.deleteMessageStream("StreamName");
} catch (e) {
// Properly handle errors.
}
});
client.onError((err) => {
// Properly handle connection errors.
// This is called only when the connection to the StreamManager server fails.
});
Node.js SDK reference: deleteMessageStream
See also
• Manage data streams on the AWS IoT Greengrass Core (p. 682)
• Configure AWS IoT Greengrass stream manager (p. 720)
• Export configurations for supported AWS Cloud destinations (p. 710)
• StreamManagerClient in the Stream Manager SDK reference:
• Python
• Java
• Node.js
Export configurations for supported AWS Cloud
destinations
User-defined Greengrass components use StreamManagerClient in the Stream Manager SDK
to interact with stream manager. When a component creates a stream (p. 695) or updates a
710
AWS IoT Greengrass Developer Guide, Version 2
Export configurations for supported cloud destinations
stream (p. 695), it passes a MessageStreamDefinition object that represents stream properties,
including the export definition. The ExportDefinition object contains the export configurations
defined for the stream. Stream manager uses these export configurations to determine where and how
to export the stream.
You can define zero or more export configurations on a stream, including multiple export configurations
for a single destination type. For example, you can export a stream to two AWS IoT Analytics channels
and one Kinesis data stream.
For failed export attempts, stream manager continually retries exporting data to the AWS Cloud at
intervals of up to five minutes. The number of retry attempts doesn't have a maximum limit.
Note
StreamManagerClient also provides a target destination you can use to export streams to an
HTTP server. This target is intended for testing purposes only. It is not stable or supported for
use in production environments.
Supported AWS Cloud destinations
• AWS IoT Analytics channels (p. 711)
• Amazon Kinesis data streams (p. 712)
• AWS IoT SiteWise asset properties (p. 713)
• Amazon S3 objects (p. 715)
You are responsible for maintaining these AWS Cloud resources.
AWS IoT Analytics channels
Stream manager supports automatic exports to AWS IoT Analytics. AWS IoT Analytics lets you perform
advanced analysis on your data to help make business decisions and improve machine learning models.
For more information, see What is AWS IoT Analytics? in the AWS IoT Analytics User Guide.
In the Stream Manager SDK, your Greengrass components use the IoTAnalyticsConfig to define
the export configuration for this destination type. For more information, see the SDK reference for your
target language:
• IoTAnalyticsConfig in the Python SDK
• IoTAnalyticsConfig in the Java SDK
• IoTAnalyticsConfig in the Node.js SDK
711
AWS IoT Greengrass Developer Guide, Version 2
Export configurations for supported cloud destinations
Requirements
This export destination has the following requirements:
• Target channels in AWS IoT Analytics must be in the same AWS account and AWS Region as the
Greengrass core device.
• The Authorize core devices to interact with AWS services (p. 790) must allow the
iotanalytics:BatchPutMessage permission to target channels. For example:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iotanalytics:BatchPutMessage"
],
"Resource": [
"arn:aws:iotanalytics:region:account-id:channel/channel_1_name",
"arn:aws:iotanalytics:region:account-id:channel/channel_2_name"
]
}
]
}
You can grant granular or conditional access to resources, for example, by using a wildcard * naming
scheme. For more information, see Adding and removing IAM policies in the IAM User Guide.
Exporting to AWS IoT Analytics
To create a stream that exports to AWS IoT Analytics, your Greengrass components create a
stream (p. 695) with an export definition that includes one or more IoTAnalyticsConfig objects.
This object defines export settings, such as the target channel, batch size, batch interval, and priority.
When your Greengrass components receive data from devices, they append messages (p. 698) that
contain a blob of data to the target stream.
Then, stream manager exports the data based on the batch settings and priority defined in the stream's
export configurations.
Amazon Kinesis data streams
Stream manager supports automatic exports to Amazon Kinesis Data Streams. Kinesis Data Streams is
commonly used to aggregate high-volume data and load it into a data warehouse or MapReduce cluster.
For more information, see What is Amazon Kinesis Data Streams? in the Amazon Kinesis Developer Guide.
In the Stream Manager SDK, your Greengrass components use the KinesisConfig to define the export
configuration for this destination type. For more information, see the SDK reference for your target
language:
• KinesisConfig in the Python SDK
• KinesisConfig in the Java SDK
• KinesisConfig in the Node.js SDK
Requirements
This export destination has the following requirements:
712
AWS IoT Greengrass Developer Guide, Version 2
Export configurations for supported cloud destinations
• Target streams in Kinesis Data Streams must be in the same AWS account and AWS Region as the
Greengrass core device.
• The Authorize core devices to interact with AWS services (p. 790) must allow the
kinesis:PutRecords permission to target data streams. For example:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kinesis:PutRecords"
],
"Resource": [
"arn:aws:kinesis:region:account-id:stream/stream_1_name",
"arn:aws:kinesis:region:account-id:stream/stream_2_name"
]
}
]
}
You can grant granular or conditional access to resources, for example, by using a wildcard * naming
scheme. For more information, see Adding and removing IAM policies in the IAM User Guide.
Exporting to Kinesis Data Streams
To create a stream that exports to Kinesis Data Streams, your Greengrass components create a
stream (p. 695) with an export definition that includes one or more KinesisConfig objects. This
object defines export settings, such as the target data stream, batch size, batch interval, and priority.
When your Greengrass components receive data from devices, they append messages (p. 698) that
contain a blob of data to the target stream. Then, stream manager exports the data based on the batch
settings and priority defined in the stream's export configurations.
Stream manager generates a unique, random UUID as a partition key for each record uploaded to
Amazon Kinesis.
AWS IoT SiteWise asset properties
Stream manager supports automatic exports to AWS IoT SiteWise. AWS IoT SiteWise lets you collect,
organize, and analyze data from industrial equipment at scale. For more information, see What is AWS
IoT SiteWise? in the AWS IoT SiteWise User Guide.
In the Stream Manager SDK, your Greengrass components use the IoTSiteWiseConfig to define the
export configuration for this destination type. For more information, see the SDK reference for your
target language:
• IoTSiteWiseConfig in the Python SDK
• IoTSiteWiseConfig in the Java SDK
• IoTSiteWiseConfig in the Node.js SDK
Note
AWS also provides AWS IoT SiteWise components, which offer a pre-built solution that you
can use to stream data from OPC-UA sources. For more information, see IoT SiteWise OPC-UA
collector (p. 409).
713
AWS IoT Greengrass Developer Guide, Version 2
Export configurations for supported cloud destinations
Requirements
This export destination has the following requirements:
• Target asset properties in AWS IoT SiteWise must be in the same AWS account and AWS Region as the
Greengrass core device.
Note
For the list of AWS Regions that AWS IoT SiteWise supports, see AWS IoT SiteWise endpoints
and quotas in the AWS General Reference.
• The Authorize core devices to interact with AWS services (p. 790) must allow the
iotsitewise:BatchPutAssetPropertyValue permission to target asset properties. The following
example policy uses the iotsitewise:assetHierarchyPath condition key to grant access to a
target root asset and its children. You can remove the Condition from the policy to allow access to all
of your AWS IoT SiteWise assets or specify ARNs of individual assets.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*",
"Condition": {
"StringLike": {
"iotsitewise:assetHierarchyPath": [
"/root node asset ID",
"/root node asset ID/*"
]
}
}
}
]
}
You can grant granular or conditional access to resources, for example, by using a wildcard * naming
scheme. For more information, see Adding and removing IAM policies in the IAM User Guide.
For important security information, see BatchPutAssetPropertyValue authorization in the AWS IoT
SiteWise User Guide.
Exporting to AWS IoT SiteWise
To create a stream that exports to AWS IoT SiteWise, your Greengrass components create a
stream (p. 695) with an export definition that includes one or more IoTSiteWiseConfig objects. This
object defines export settings, such as the batch size, batch interval, and priority.
When your Greengrass components receive asset property data from devices, they append messages that
contain the data to the target stream. Messages are JSON-serialized PutAssetPropertyValueEntry
objects that contain property values for one or more asset properties. For more information, see Append
message (p. 699) for AWS IoT SiteWise export destinations.
Note
When you send data to AWS IoT SiteWise, your data must meet the requirements
of the BatchPutAssetPropertyValue action. For more information, see
BatchPutAssetPropertyValue in the AWS IoT SiteWise API Reference.
Then, stream manager exports the data based on the batch settings and priority defined in the stream's
export configurations.
714
AWS IoT Greengrass Developer Guide, Version 2
Export configurations for supported cloud destinations
You can adjust your stream manager settings and Greengrass component logic to design your export
strategy. For example:
• For near real time exports, set low batch size and interval settings and append the data to the stream
when it's received.
• To optimize batching, mitigate bandwidth constraints, or minimize cost, your Greengrass components
can pool the timestamp-quality-value (TQV) data points received for a single asset property before
appending the data to the stream. One strategy is to batch entries for up to 10 different property-
asset combinations, or property aliases, in one message instead of sending more than one entry for
the same property. This helps stream manager to remain within AWS IoT SiteWise quotas.
Amazon S3 objects
Stream manager supports automatic exports to Amazon S3. You can use Amazon S3 to store and retrieve
large amounts of data. For more information, see What is Amazon S3? in the Amazon Simple Storage
Service Developer Guide.
In the Stream Manager SDK, your Greengrass components use the S3ExportTaskExecutorConfig to
define the export configuration for this destination type. For more information, see the SDK reference
for your target language:
• S3ExportTaskExecutorConfig in the Python SDK
• S3ExportTaskExecutorConfig in the Java SDK
• S3ExportTaskExecutorConfig in the Node.js SDK
Requirements
This export destination has the following requirements:
• Target Amazon S3 buckets must be in the same AWS account as the Greengrass core device.
• If a Lambda function that runs in Greengrass container mode writes input files to an input file
directory, you must mount the directory as a volume in the container with write permissions. This
ensures that the files are written to the root file system and visible to the stream manager component,
which runs outside the container.
• If a Docker container component writes input files to an input file directory, you must mount the
directory as a volume in the container with write permissions. This ensures that the files are written to
the root file system and visible to the stream manager component, which runs outside the container.
• The Authorize core devices to interact with AWS services (p. 790) must allow the following
permissions to the target buckets. For example:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:AbortMultipartUpload",
"s3:ListMultipartUploadParts"
],
"Resource": [
"arn:aws:s3:::bucket-1-name/*",
"arn:aws:s3:::bucket-2-name/*"
]
}
]
715
AWS IoT Greengrass Developer Guide, Version 2
Export configurations for supported cloud destinations
You can grant granular or conditional access to resources, for example, by using a wildcard * naming
scheme. For more information, see Adding and removing IAM policies in the IAM User Guide.
Exporting to Amazon S3
To create a stream that exports to Amazon S3, your Greengrass components use the
S3ExportTaskExecutorConfig object to configure the export policy. The policy defines export
settings, such as the multipart upload threshold and priority. For Amazon S3 exports, stream manager
uploads data that it reads from local files on the core device. To initiate an upload, your Greengrass
components append an export task to the target stream. The export task contains information about
the input file and target Amazon S3 object. Stream manager runs tasks in the sequence that they are
appended to the stream.
Note
The target bucket must already exist in your AWS account. If an object for the specified key
doesn't exist, stream manager creates the object for you.
Stream manager uses the multipart upload threshold property, minimum part size (p. 722) setting,
and size of the input file to determine how to upload data. The multipart upload threshold must be
greater or equal to the minimum part size. If you want to upload data in parallel, you can create multiple
streams.
The keys that specify your target Amazon S3 objects can include valid Java DateTimeFormatter strings
in !{timestamp:value} placeholders. You can use these timestamp placeholders to partition data
in Amazon S3 based on the time that the input file data was uploaded. For example, the following key
name resolves to a value such as my-key/2020/12/31/data.txt.
my-key/!{timestamp:YYYY}/!{timestamp:MM}/!{timestamp:dd}/data.txt
Note
If you want to monitor the export status for a stream, first create a status stream and then
configure the export stream to use it. For more information, see the section called “Monitor
export tasks” (p. 717).
Manage input data
You can author code that IoT applications use to manage the lifecycle of the input data. The following
example workflow shows how you might use Greengrass components to manage this data.
1. A local process receives data from devices or peripherals, and then writes the data to files in a
directory on the core device. These are the input files for stream manager.
2. A Greengrass component scans the directory and appends an export task (p. 701) to the target
stream when a new file is created. The task is a JSON-serialized S3ExportTaskDefinition object
that specifies the URL of the input file, the target Amazon S3 bucket and key, and optional user
metadata.
3. Stream manager reads the input file and exports the data to Amazon S3 in the order of appended
tasks. The target bucket must already exist in your AWS account. If an object for the specified key
doesn't exist, stream manager creates the object for you.
4. The Greengrass component reads messages (p. 702) from a status stream to monitor the export
status. After export tasks are completed, the Greengrass component can delete the corresponding
input files. For more information, see the section called “Monitor export tasks” (p. 717).
716
AWS IoT Greengrass Developer Guide, Version 2
Export configurations for supported cloud destinations
Monitor export tasks
You can author code that IoT applications use to monitor the status of your Amazon S3 exports. Your
Greengrass components must create a status stream and then configure the export stream to write
status updates to the status stream. A single status stream can receive status updates from multiple
streams that export to Amazon S3.
First, create a stream (p. 695) to use as the status stream. You can configure the size and retention
policies for the stream to control the lifespan of the status messages. For example:
• Set Persistence to Memory if you don't want to store the status messages.
• Set StrategyOnFull to OverwriteOldestData so that new status messages are not lost.
Then, create or update the export stream to use the status stream. Specifically, set the status
configuration property of the stream’s S3ExportTaskExecutorConfig export configuration. This
setting tells stream manager to write status messages about the export tasks to the status stream. In the
StatusConfig object, specify the name of the status stream and the level of verbosity. The following
supported values range from least verbose (ERROR) to most verbose (TRACE). The default is INFO.
• ERROR
• WARN
• INFO
• DEBUG
• TRACE
The following example workflow shows how Greengrass components might use a status stream to
monitor export status.
1. As described in the previous workflow, a Greengrass component appends an export task (p. 701) to
a stream that's configured to write status messages about export tasks to a status stream. The append
operation return a sequence number that represents the task ID.
2. A Greengrass component reads messages (p. 702) sequentially from the status stream, and then
filters the messages based on the stream name and task ID or based on an export task property from
the message context. For example, the Greengrass component can filter by the input file URL of the
export task, which is represented by the S3ExportTaskDefinition object in the message context.
The following status codes indicate that an export task has reached a completed state:
• Success. The upload was completed successfully.
• Failure. Stream manager encountered an error, for example, the specified bucket does not exist.
After resolving the issue, you can append the export task to the stream again.
• Canceled. The task was stopped because the stream or export definition was deleted, or the time-
to-live (TTL) period of the task expired.
Note
The task might also have a status of InProgress or Warning. Stream manager issues
warnings when an event returns an error that doesn't affect the execution of the task. For
example, a failure to clean up a partial upload returns a warning.
3. After export tasks are completed, the Greengrass component can delete the corresponding input files.
The following example shows how a Greengrass component might read and process status messages.
Python
import time
717
AWS IoT Greengrass Developer Guide, Version 2
Export configurations for supported cloud destinations
from stream_manager import (
ReadMessagesOptions,
Status,
StatusConfig,
StatusLevel,
StatusMessage,
StreamManagerClient,
)
from stream_manager.util import Util
client = StreamManagerClient()
try:
# Read the statuses from the export status stream
is_file_uploaded_to_s3 = False
while not is_file_uploaded_to_s3:
try:
messages_list = client.read_messages(
"StatusStreamName", ReadMessagesOptions(min_message_count=1,
read_timeout_millis=1000)
)
for message in messages_list:
# Deserialize the status message first.
status_message = Util.deserialize_json_bytes_to_obj(message.payload,
StatusMessage)
# Check the status of the status message. If the status is "Success",
# the file was successfully uploaded to S3.
# If the status was either "Failure" or "Cancelled", the server was
unable to upload the file to S3.
# We will print the message for why the upload to S3 failed from the
status message.
# If the status was "InProgress", the status indicates that the server
has started uploading
# the S3 task.
if status_message.status == Status.Success:
logger.info("Successfully uploaded file at path " + file_url + " to
S3.")
is_file_uploaded_to_s3 = True
elif status_message.status == Status.Failure or status_message.status
== Status.Canceled:
logger.info(
"Unable to upload file at path " + file_url + " to S3. Message:
" + status_message.message
)
is_file_uploaded_to_s3 = True
time.sleep(5)
except StreamManagerException:
logger.exception("Exception while running")
except StreamManagerException:
pass
# Properly handle errors.
except ConnectionError or asyncio.TimeoutError:
pass
# Properly handle errors.
Python SDK reference: read_messages | StatusMessage
Java
import com.amazonaws.greengrass.streammanager.client.StreamManagerClient;
import com.amazonaws.greengrass.streammanager.client.StreamManagerClientFactory;
import com.amazonaws.greengrass.streammanager.client.utils.ValidateAndSerialize;
import com.amazonaws.greengrass.streammanager.model.ReadMessagesOptions;
import com.amazonaws.greengrass.streammanager.model.Status;
718
AWS IoT Greengrass Developer Guide, Version 2
Export configurations for supported cloud destinations
import com.amazonaws.greengrass.streammanager.model.StatusConfig;
import com.amazonaws.greengrass.streammanager.model.StatusLevel;
import com.amazonaws.greengrass.streammanager.model.StatusMessage;
try (final StreamManagerClient client = StreamManagerClientFactory.standard().build())
{
try {
boolean isS3UploadComplete = false;
while (!isS3UploadComplete) {
try {
// Read the statuses from the export status stream
List<Message> messages = client.readMessages("StatusStreamName",
new
ReadMessagesOptions().withMinMessageCount(1L).withReadTimeoutMillis(1000L));
for (Message message : messages) {
// Deserialize the status message first.
StatusMessage statusMessage =
ValidateAndSerialize.deserializeJsonBytesToObj(message.getPayload(),
StatusMessage.class);
// Check the status of the status message. If the status is
"Success", the file was successfully uploaded to S3.
// If the status was either "Failure" or "Canceled", the server was
unable to upload the file to S3.
// We will print the message for why the upload to S3 failed from
the status message.
// If the status was "InProgress", the status indicates that the
server has started uploading the S3 task.
if (Status.Success.equals(statusMessage.getStatus())) {
System.out.println("Successfully uploaded file at path " +
FILE_URL + " to S3.");
isS3UploadComplete = true;
} else if (Status.Failure.equals(statusMessage.getStatus()) ||
Status.Canceled.equals(statusMessage.getStatus())) {
System.out.println(String.format("Unable to upload file at path
%s to S3. Message %s",
statusMessage.getStatusContext().getS3ExportTaskDefinition().getInputUrl(),
statusMessage.getMessage()));
sS3UploadComplete = true;
}
}
} catch (StreamManagerException ignored) {
} finally {
// Sleep for sometime for the S3 upload task to complete before trying
to read the status message.
Thread.sleep(5000);
}
} catch (e) {
// Properly handle errors.
}
} catch (StreamManagerException e) {
// Properly handle exception.
}
Java SDK reference: readMessages | StatusMessage
Node.js
const {
StreamManagerClient, ReadMessagesOptions,
Status, StatusConfig, StatusLevel, StatusMessage,
util,
} = require(*'aws-greengrass-stream-manager-sdk'*);
const client = new StreamManagerClient();
719
AWS IoT Greengrass Developer Guide, Version 2
Configure stream manager
client.onConnected(async () => {
try {
let isS3UploadComplete = false;
while (!isS3UploadComplete) {
try {
// Read the statuses from the export status stream
const messages = await c.readMessages("StatusStreamName",
new ReadMessagesOptions()
.withMinMessageCount(1)
.withReadTimeoutMillis(1000));
messages.forEach((message) => {
// Deserialize the status message first.
const statusMessage =
util.deserializeJsonBytesToObj(message.payload, StatusMessage);
// Check the status of the status message. If the status is
'Success', the file was successfully uploaded to S3.
// If the status was either 'Failure' or 'Cancelled', the server
was unable to upload the file to S3.
// We will print the message for why the upload to S3 failed from
the status message.
// If the status was "InProgress", the status indicates that the
server has started uploading the S3 task.
if (statusMessage.status === Status.Success) {
console.log(`Successfully uploaded file at path ${FILE_URL} to
S3.`);
isS3UploadComplete = true;
} else if (statusMessage.status === Status.Failure ||
statusMessage.status === Status.Canceled) {
console.log(`Unable to upload file at path ${FILE_URL} to S3.
Message: ${statusMessage.message}`);
isS3UploadComplete = true;
}
});
// Sleep for sometime for the S3 upload task to complete before trying
to read the status message.
await new Promise((r) => setTimeout(r, 5000));
} catch (e) {
// Ignored
}
} catch (e) {
// Properly handle errors.
}
});
client.onError((err) => {
// Properly handle connection errors.
// This is called only when the connection to the StreamManager server fails.
});
Node.js SDK reference: readMessages | StatusMessage
Configure AWS IoT Greengrass stream manager
On Greengrass core devices, stream manager can store, process, and export IoT device data. Stream
manager provides parameters that you use to configure runtime settings. These settings apply to all
streams on the Greengrass core device. You can use the AWS IoT Greengrass console or API to configure
stream manager settings when you deploy the component. Changes take effect after the deployment
completes.
720
AWS IoT Greengrass Developer Guide, Version 2
Stream manager parameters
Stream manager parameters
Stream manager provides the following parameters that you can configure when you deploy the
component to your core devices. All parameters are optional.
Storage directory
Parameter name: STREAM_MANAGER_STORE_ROOT_DIR
The absolute path of the local directory used to store streams. This value must start with a forward
slash (for example, /data).
For information about securing stream data, see the section called “Local data security” (p. 683).
Server port
Parameter name: STREAM_MANAGER_SERVER_PORT
The local port number used to communicate with stream manager. The default is 8088.
You can specify 0 to use a random available port.
Authenticate client
Parameter name: STREAM_MANAGER_AUTHENTICATE_CLIENT
Indicates whether clients must be authenticated to interact with stream manager. All interaction
between clients and stream manager is controlled by the Stream Manager SDK. This parameter
determines which clients can call the Stream Manager SDK to work with streams. For more
information, see the section called “Client authentication” (p. 684).
Valid values are true or false. The default is true (recommended).
• true. Allows only Greengrass components as clients. Components use internal AWS IoT
Greengrass Core protocols to authenticate with the Stream Manager SDK.
• false. Allows any process that runs on the AWS IoT Greengrass Core to be a client. Do not set
the value to false unless your business case requires it. For example, use false only if non-
component processes on the core device must communicate directly with stream manager.
Maximum bandwidth
Parameter name: STREAM_MANAGER_EXPORTER_MAX_BANDWIDTH
The average maximum bandwidth (in kilobits per second) that can be used to export data. The
default allows unlimited use of available bandwidth.
Thread pool size
Parameter name: STREAM_MANAGER_EXPORTER_THREAD_POOL_SIZE
The maximum number of active threads that can be used to export data. The default is 5.
The optimal size depends on your hardware, stream volume, and planned number of export streams.
If your export speed is slow, you can adjust this setting to find the optimal size for your hardware
and business case. The CPU and memory of your core device hardware are limiting factors. To start,
you might try setting this value equal to the number of processor cores on the device.
Be careful not to set a size that's higher than your hardware can support. Each stream consumes
hardware resources, so try to limit the number of export streams on constrained devices.
JVM arguments
Parameter name: JVM_ARGS
721
AWS IoT Greengrass Developer Guide, Version 2
See also
Custom Java Virtual Machine arguments to pass to stream manager at startup. Multiple arguments
should be separated by spaces.
Use this parameter only when you must override the default settings used by the JVM. For example,
you might need to increase the default heap size if you plan to export a large number of streams.
Logging level
Parameter name: LOG_LEVEL
The logging configuration for the component. Choose from the following log levels, listed here in
level order:
• DEBUG
• INFO
• WARN
• ERROR
Default: INFO
Minimum size for multipart upload
Parameter name:
STREAM_MANAGER_EXPORTER_S3_DESTINATION_MULTIPART_UPLOAD_MIN_PART_SIZE_BYTES
The minimum size (in bytes) of a part in a multipart upload to Amazon S3. Stream manager uses this
setting and the size of the input file to determine how to batch data in a multipart PUT request. The
default and minimum value is 5242880 bytes (5 MB).
Note
Stream manager uses the stream's sizeThresholdForMultipartUploadBytes property
to determine whether to export to Amazon S3 as a single or multipart upload. User-defined
Greengrass components set this threshold when they create a stream that exports to
Amazon S3. The default threshold is 5 MB.
See also
• Manage data streams on the AWS IoT Greengrass Core (p. 682)
• Use StreamManagerClient to work with streams (p. 695)
• Export configurations for supported AWS Cloud destinations (p. 710)
722
AWS IoT Greengrass Developer Guide, Version 2
How AWS IoT Greengrass ML inference works
Perform machine learning inference
With AWS IoT Greengrass, you can perform machine learning (ML) inference on your edge devices on
locally generated data using cloud-trained models. You benefit from the low latency and cost savings
of running local inference, yet still take advantage of cloud computing power for training models and
complex processing.
AWS IoT Greengrass simplifies the steps required to perform inference. You can train your inference
models anywhere and deploy them locally as machine learning components. For example, you can build
and train deep-learning models in Amazon SageMaker and store them in an Amazon S3 bucket. You can
then use these models as artifacts in your components to perform inference on your core devices.
Topics
• How AWS IoT Greengrass ML inference works (p. 723)
• What's different in Version 2? (p. 724)
• Requirements (p. 724)
• Supported model sources (p. 724)
• Supported machine learning runtimes (p. 725)
• AWS-provided machine learning components (p. 725)
• Tutorial: Perform sample image classification inference using TensorFlow Lite (p. 729)
• Perform sample image classification inference on images from a camera using TensorFlow
Lite (p. 733)
• Use Amazon SageMaker Edge Manager on Greengrass core devices (p. 738)
• Customize your machine learning components (p. 746)
• Troubleshooting machine learning inference (p. 757)
How AWS IoT Greengrass ML inference works
AWS provides machine learning components (p. 725) that you can use as-is to create one-click
deployments to perform machine learning inference on your device. You can also use these components
as templates to create custom components to meet your specific requirements.
AWS-provided machine learning components are broadly categorized as follows:
• Model component—Contains machine learning models as Greengrass artifacts.
• Runtime component—Contains the script that installs the machine learning framework and its
dependencies on the Greengrass core device.
• Inference component—Contains the inference code and includes component dependencies to install
the machine learning framework and download pre-trained machine learning models.
Each deployment that you create to perform machine learning inference consists of at least one
component that runs your inference application, installs the machine learning framework, and
downloads your machine learning models. To perform sample inference with AWS-provided components,
you deploy an inference component to your core device, which automatically includes the corresponding
model and runtime components as dependencies. To customize your deployments, you can plug in or
swap out the sample model components with custom model components, or you can use the component
recipes for the AWS-provided components as templates to create your own custom inference, model, and
runtime components.
At a high level, you can complete the following steps to perform machine learning inference using
custom components:
723
AWS IoT Greengrass Developer Guide, Version 2
What's different in Version 2?
1. Create a model component. This component contains the machine learning models that you want to
use to perform inference. AWS provides sample pre-trained DLR and TensorFlow Lite models. To use
custom model, create your own model component.
2. Create a runtime component. This component contains the scripts required to install the machine
learning runtime for your models. AWS provides sample runtime components for Deep Learning
Runtime (DLR) and TensorFlow Lite. To use other runtimes with your custom models and inference
code, create your own runtime components.
3. Create an inference component. This component contains your inference code, and includes your
model and runtime components as dependencies. AWS-provides sample inference components for
image classification and object detection using DLR and TensorFlow Lite. To perform other types of
inference, or to use custom models and runtimes, create your own inference component.
4. Deploy the inference component. When you deploy this component, AWS IoT Greengrass also
automatically deploys the model and runtime component dependencies.
To get started with AWS-provided components, see the section called “Perform sample image
classification inference” (p. 729).
For information about creating custom machine learning components, see Customize your machine
learning components (p. 746).
What's different in Version 2?
AWS IoT Greengrass consolidates functional units for machine learning—such as models, runtimes, and
inference code— into components that enable you to use a one-click process to install the machine
learning runtime, download your trained models, and perform inference on your device.
The AWS-provided machine learning components provide you with the flexibility to quickly get started
performing machine learning inference with sample inference code and pre-trained models. You can
plug in custom model components to use your own custom-trained models with the inference and
runtime components that AWS provides. For a completely customized machine learning solution, you can
use the public components as templates to create custom components and use any runtime, model, or
inference type that you want.
Requirements
The following requirements apply for creating and using machine learning components:
• A Greengrass core device. If you don't have one, see Getting started with AWS IoT Greengrass
V2 (p. 31).
• Minimum 500 MB local storage space to use AWS-provided sample machine learning components.
Supported model sources
AWS IoT Greengrass supports using custom-trained machine learning models that are stored in Amazon
S3. You can also use Amazon SageMaker edge packaging jobs to directly create model components for
your SageMaker Neo-compiled models. For information about using SageMaker Edge Manager with AWS
IoT Greengrass, see Use Amazon SageMaker Edge Manager on Greengrass core devices (p. 738).
The following requirements apply to the S3 buckets that contain your models:
• S3 buckets must not be encrypted using SSE-C. For buckets that use server-side encryption, AWS IoT
Greengrass machine learning inference currently supports the SSE-S3 or SSE-KMS encryption options
724
AWS IoT Greengrass Developer Guide, Version 2
Supported runtimes
only. For more information about server-side encryption options, see Protecting data using server-side
encryption in the Amazon Simple Storage Service User Guide.
• The names of S3 buckets must not include periods (.). For more information, see the rule about using
virtual hosted-style buckets with SSL in Rules for bucket naming in the Amazon Simple Storage Service
User Guide.
• The S3 buckets that store your model sources must be in the same AWS account and AWS Region as
your machine learning components.
• AWS IoT Greengrass must have read permission to the model source. To enable AWS IoT Greengrass
to access the S3 buckets, the Greengrass device role (p. 790) must allow the s3:GetObject
action. For more information about the device role, see Authorize core devices to interact with AWS
services (p. 790).
Supported machine learning runtimes
AWS IoT Greengrass enables you to create custom components to use any machine learning runtime of
your choice to perform machine learning inference with your custom-trained models. For information
about creating custom machine learning components, see Customize your machine learning
components (p. 746).
To simplify the process of getting started with machine learning, AWS IoT Greengrass provides sample
inference, model, and runtime components that use the following machine learning runtimes:
• Deep Learning Runtime (DLR) v1.6.0 and v1.3.0
• TensorFlow Lite v2.5.0
AWS-provided machine learning components
The following table lists the AWS-provided components used for machine learning.
Note
Several AWS-provided components depend on specific minor versions of the Greengrass
nucleus. Because of this dependency, you need to update these components when you update
the Greengrass nucleus to a new minor version. For information about the specific versions
of the nucleus that each component depends on, see the corresponding component topic.
For more information about updating the nucleus, see Update the AWS IoT Greengrass Core
software (OTA) (p. 170).
Component Description Depends Component Supported Open
on type (p. 441)OS source (p. 921)
nucleus
SageMaker Edge Deploys the Yes Generic Linux, No
Manager (p. 292) Amazon Windows
SageMaker
Edge Manager
agent on the
Greengrass
core device.
DLR image classification (p. 299) Inference Yes Generic Linux, No
component Windows
that uses the
DLR image
725
AWS IoT Greengrass Developer Guide, Version 2
Machine learning components
Component Description Depends Component Supported Open
on type (p. 441)OS source (p. 921)
nucleus
classification
model store
and the DLR
runtime
component as
dependencies
to install DLR,
download
sample image
classification
models, and
perform
image
classification
inference on
supported
devices.
DLR object detection (p. 306) Inference Yes Generic Linux, No
component Windows
that uses the
DLR object
detection
model store
and the DLR
runtime
component as
dependencies
to install DLR,
download
sample object
detection
models, and
perform
object
detection
inference on
supported
devices.
DLR image classification model Model Yes Generic Linux, No
store (p. 313) component Windows
that contains
sample
ResNet-50
image
classification
models as
Greengrass
artifacts.
726
AWS IoT Greengrass Developer Guide, Version 2
Machine learning components
Component Description Depends Component Supported Open
on type (p. 441)OS source (p. 921)
nucleus
DLR object detection model Model Yes Generic Linux, No
store (p. 316) component Windows
that contains
sample
YOLOv3
object
detection
models as
Greengrass
artifacts.
DLR installer (p. 319) Runtime Yes Generic Linux, No
component Windows
that contains
an installation
script that is
used to install
DLR and its
dependencies
on the
Greengrass
core device.
TensorFlow Lite image Inference Yes Generic Linux, No
classification (p. 324) component Windows
that uses the
TensorFlow
Lite image
classification
model store
and the
TensorFlow
Lite runtime
component as
dependencies
to install
TensorFlow
Lite,
download
sample image
classification
models, and
perform
image
classification
inference on
supported
devices.
727
AWS IoT Greengrass Developer Guide, Version 2
Machine learning components
Component Description Depends Component Supported Open
on type (p. 441)OS source (p. 921)
nucleus
TensorFlow Lite object Inference Yes Generic Linux, No
detection (p. 329) component Windows
that uses the
TensorFlow
Lite object
detection
model store
and the
TensorFlow
Lite runtime
component as
dependencies
to install
TensorFlow
Lite,
download
sample object
detection
models, and
perform
object
detection
inference on
supported
devices.
TensorFlow Lite image Model Yes Generic Linux, No
classification model store (p. 334) component Windows
that contains
a sample
MobileNet v1
model as a
Greengrass
artifact.
TensorFlow Lite object detection Model Yes Generic Linux, No
model store (p. 337) component Windows
that contains
a sample
Single Shot
Detection
(SSD)
MobileNet
model as a
Greengrass
artifact.
728
AWS IoT Greengrass Developer Guide, Version 2
Perform sample image classification inference
Component Description Depends Component Supported Open
on type (p. 441)OS source (p. 921)
nucleus
TensorFlow Lite installer (p. 339) Runtime Yes Generic Linux, No
component Windows
that contains
an installation
script that is
used to install
TensorFlow
Lite and its
dependencies
on the
Greengrass
core device.
Tutorial: Perform sample image classification
inference using TensorFlow Lite
This tutorial shows you how to use the TensorFlow Lite image classification (p. 324) inference component
to perform sample image classification inference on a Greengrass core device. This component includes
the following component dependencies:
• TensorFlow Lite image classification model store component
• TensorFlow Lite component
When you deploy this component, it downloads a pre-trained MobileNet v1 model and installs the
TensorFlow Lite runtime and its dependencies. This component publishes inference results on the ml/
tflite/image-classification topic. To view these inference results, use the AWS IoT MQTT client
in the AWS IoT console to subscribe to this topic.
In this tutorial you deploy the sample inference component to perform image classification on the
sample image that is provided by AWS IoT Greengrass. After you complete this tutorial, you can
complete Perform sample image classification inference on images from a camera using TensorFlow
Lite (p. 733), which shows you how to modify the sample inference component to perform image
classification on images from a camera locally on a Greengrass core device.
Topics
• Prerequisites (p. 729)
• Step 1: Subscribe to the default notifications topic (p. 730)
• Step 2: Deploy the TensorFlow Lite image classification component (p. 730)
• Step 3: View inference results (p. 731)
• Next steps (p. 733)
Prerequisites
To complete this tutorial, you need the following:
• A Linux Greengrass core device. If you don't have one, see Getting started with AWS IoT Greengrass
V2 (p. 31).
729
AWS IoT Greengrass Developer Guide, Version 2
Step 1: Subscribe to the default notifications topic
• If you are using an Armv7l device such as Raspberry Pi, dependencies for OpenCV Python installed on
the device. Run the following command to install the dependencies:
sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-
dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
Step 1: Subscribe to the default notifications topic
In this step, you configure the AWS IoT MQTT client in the AWS IoT console to watch MQTT messages
published by the TensorFlow Lite image classification component. By default, the component publishes
inference results on the ml/tflite/image-classification topic. Subscribe to this topic before you
deploy the component to your Greengrass core device to see the inference results when the component
runs for the first time.
To subscribe to the default notifications topic
1. In the AWS IoT console navigation menu, choose Test, MQTT test client.
2. Under Subscribe to a topic, in the Topic name box, enter ml/tflite/image-classification.
3. Choose Subscribe.
Step 2: Deploy the TensorFlow Lite image
classification component
In this step, you deploy the TensorFlow Lite image classification component to your core device:
To deploy the TensorFlow Lite image classification component (console)
1. In the AWS IoT Greengrass console navigation menu, choose Components.
2. On the Components page, on the Public components tab, choose
aws.greengrass.TensorFlowLiteImageClassification.
3. On the aws.greengrass.TensorFlowLiteImageClassification page, choose Deploy.
4. From Add to deployment, choose one of the following:
a. To merge this component to an existing deployment on your target device, choose Add to
existing deployment, and then select the deployment that you want to revise.
b. To create a new deployment on your target device, choose Create new deployment. If you have
an existing deployment on your device, choosing this step replaces the existing deployment.
5. On the Specify target page, do the following:
a. Under Deployment information, enter or modify the friendly name for your deployment.
b. Under Deployment targets, select a target for your deployment, and choose Next. You cannot
change the deployment target if you are revising an existing deployment.
6. On the Select components page, under Public components, verify that the
aws.greengrass.TensorFlowLiteImageClassification component is selected, and choose
Next.
7. On the Configure components page, keep the default configuration settings, and choose Next.
8. On the Configure advanced settings page, keep the default configuration settings, and choose
Next.
730
AWS IoT Greengrass Developer Guide, Version 2
Step 3: View inference results
9. On the Review page, choose Deploy
To deploy the TensorFlow Lite image classification component (AWS CLI)
1. Create a deployment.json file to define the deployment configuration for the TensorFlow Lite
image classification component. This file should look like the following:
{
"targetArn":"targetArn",
"components": {
"aws.greengrass.TensorFlowLiteImageClassification": {
"componentVersion": 2.1.0,
"configurationUpdate": {
}
}
}
}
• In the targetArn field, replace targetArn with the Amazon Resource Name (ARN) of the thing
or thing group to target for the deployment, in the following format:
• Thing: arn:aws:iot:region:account-id:thing/thingName
• Thing group: arn:aws:iot:region:account-id:thinggroup/thingGroupName
• This tutorial uses component version 2.1.0. In the
aws.greengrass.TensorFlowLiteObjectDetection component object, replace 2.1.0 to
use a different version of the TensorFlow Lite object detection component.
2. Run the following command to deploy the TensorFlow Lite image classification component on the
device:
$ aws greengrassv2 create-deployment \
--cli-input-json file://path/to/deployment.json
The deployment can take several minutes to complete. In the next step, check the component log to
verify that the deployment completed successfully and to view the inference results.
Step 3: View inference results
After you deploy the component, you can view the inference results in the component log on your
Greengrass core device and in the AWS IoT MQTT client in the AWS IoT console. To subscribe to the topic
on which the component publishes inference results, see Step 1: Subscribe to the default notifications
topic (p. 730).
• AWS IoT MQTT client—To view the results that the inference component publishes on the default
notifications topic (p. 730), complete the following steps:
1. In the AWS IoT console navigation menu, choose Test, MQTT test client.
2. Under Subscriptions, choose ml/tflite/image-classification.
You should see messages similar to the following example.
{
"timestamp": "2021-01-01 00:00:00.000000",
"inference-type": "image-classification",
"inference-description": "Top 5 predictions with score 0.3 or above ",
"inference-results": [
{
731
AWS IoT Greengrass Developer Guide, Version 2
Step 3: View inference results
"Label": "cougar, puma, catamount, mountain lion, painter, panther, Felis
concolor",
"Score": "0.5882352941176471"
},
{
"Label": "Persian cat",
"Score": "0.5882352941176471"
},
{
"Label": "tiger cat",
"Score": "0.5882352941176471"
},
{
"Label": "dalmatian, coach dog, carriage dog",
"Score": "0.5607843137254902"
},
{
"Label": "malamute, malemute, Alaskan malamute",
"Score": "0.5450980392156862"
}
]
}
• Component log—To view the inference results in the component log, run the following command on
your Greengrass core device.
sudo tail -f /greengrass/v2/logs/aws.greengrass.TensorFlowLiteImageClassification.log
You should see results similar to the following example.
2021-01-01 00:00:00.000000 [INFO] (Copier)
aws.greengrass.TensorFlowLiteImageClassification: stdout. Publishing results to the IoT
core....
{scriptName=services.aws.greengrass.TensorFlowLiteImageClassification.lifecycle.Run.script,
serviceName=aws.greengrass.TensorFlowLiteImageClassification, currentState=RUNNING}
2021-01-01 00:00:00.000000 [INFO] (Copier)
aws.greengrass.TensorFlowLiteImageClassification: stdout. {"timestamp":
"2021-01-01 00:00:00.000000", "inference-type": "image-classification", "inference-
description": "Top 5 predictions with score 0.3 or above ", "inference-results":
[{"Label": "cougar, puma, catamount, mountain lion, painter, panther, Felis
concolor", "Score": "0.5882352941176471"}, {"Label": "Persian cat", "Score":
"0.5882352941176471"}, {"Label": "tiger cat", "Score": "0.5882352941176471"},
{"Label": "dalmatian, coach dog, carriage dog", "Score": "0.5607843137254902"},
{"Label": "malamute, malemute, Alaskan malamute", "Score": "0.5450980392156862"}]}.
{scriptName=services.aws.greengrass.TensorFlowLiteImageClassification.lifecycle.Run.script,
serviceName=aws.greengrass.TensorFlowLiteImageClassification, currentState=RUNNING}
If you can't see inference results in the component log or in the MQTT client, the deployment failed or
didn't reach the core device. This can occur if your core device isn't connected to the internet or doesn't
have the right permissions to run the component. Run the following command on your core device to
view the AWS IoT Greengrass Core software log file. This file includes logs from the Greengrass core
device's deployment service.
sudo tail -f /greengrass/v2/logs/greengrass.log
For more information, see Troubleshooting machine learning inference (p. 757).
732
AWS IoT Greengrass Developer Guide, Version 2
Next steps
Next steps
If you have a Greengrass core device with a supported camera interface, you can complete Perform
sample image classification inference on images from a camera using TensorFlow Lite (p. 733), which
shows you how to modify the sample inference component to perform image classification on images
from a camera.
To further explore the configuration of the sample TensorFlow Lite image classification (p. 324) inference
component, try the following:
• Modify the InferenceInterval configuration parameter to change how often the inference code
runs.
• Modify the ImageName and ImageDirectory configuration parameters in the inference component
configuration to specify a custom image to use for inference.
For information about customizing the configuration of public components or creating custom machine
learning components, see Customize your machine learning components (p. 746).
Perform sample image classification inference on
images from a camera using TensorFlow Lite
This tutorial shows you how to use the TensorFlow Lite image classification (p. 324) inference component
to perform sample image classification inference on images from a camera locally on a Greengrass core
device. This component includes the following component dependencies:
• TensorFlow Lite image classification model store component
• TensorFlow Lite component
Note
This tutorial accesses the camera module for Raspberry Pi, NVIDIA Jetson Nano, or AWS
DeepLens devices, but AWS IoT Greengrass supports other devices on Armv7l, Armv8, or x86_64
platforms. To set up a camera for a different device, consult the relevant documentation for
your device.
Topics
• Prerequisites (p. 733)
• Step 1: Configure the camera module on your device (p. 734)
• Step 2: Verify your subscription to the default notifications topic (p. 736)
• Step 3: Modify the TensorFlow Lite image classification component configuration and deploy
it (p. 736)
• Step 4: View inference results (p. 738)
• Next steps (p. 738)
Prerequisites
To complete this tutorial, you must first complete Tutorial: Perform sample image classification inference
using TensorFlow Lite (p. 729).
You also need the following:
733
AWS IoT Greengrass Developer Guide, Version 2
Step 1: Configure the camera module on your device
• A Linux Greengrass core device with a camera interface. This tutorial accesses the camera module on
one the following supported devices:
• Raspberry Pi running Raspberry Pi OS (previously called Raspbian)
• NVIDIA Jetson Nano
• AWS DeepLens
For information about setting up a Greengrass core device, see Getting started with AWS IoT
Greengrass V2 (p. 31).
• For Raspberry Pi or NVIDIA Jetson Nano devices, Raspberry Pi Camera Module V2 - 8 megapixel,
1080p. To learn how to set up the camera, see Connecting the camera in the Raspberry Pi
documentation.
• Dependencies for OpenCV Python installed on the device. This requirement is applicable only for
Armv7l devices such as the Raspberry Pi that is used in this tutorial. You don't need to meet this
requirement for other devices.
Run the following command to install the dependencies:
sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-
dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
Step 1: Configure the camera module on your device
In this step, you install and enable the camera module for your device. Run the following commands on
the device.
Raspberry Pi (Armv7l)
1. Install the picamera interface for the camera module. Run the following command to install
the camera module and the other Python libraries that are required for this tutorial.
sudo apt-get install -y python3-picamera
2. Verify that Picamera installed successfully.
sudo -u ggc_user bash -c 'python3 -c "import picamera"'
If the output doesn't contain errors, the validation is successful.
Note
If the Python executable file that is installed on your device is python3.7, use
python3.7 instead of python3 for the commands in this tutorial. Make sure that
your pip installation maps to the correct python3.7 or python3 version to avoid
dependency errors.
3. Reboot the device.
sudo reboot
4. Open the Raspberry Pi configuration tool.
sudo raspi-config
5. Use the arrow keys to open Interfacing Options and enable the camera interface. If prompted,
allow the device to reboot.
6. Run the following command to test the camera setup.
734
AWS IoT Greengrass Developer Guide, Version 2
Step 1: Configure the camera module on your device
raspistill -v -o test.jpg
This opens a preview window on the Raspberry Pi, saves a picture named test.jpg to your
current directory, and displays information about the camera in the Raspberry Pi terminal.
7. Run the following command to create a symlink to enable the inference component to access
your camera from the virtual environment that is created by the runtime component.
sudo ln -s /usr/lib/python3/dist-packages/picamera "MLRootPath/
greengrass_ml_tflite_venv/lib/python3.7/site-packages"
The default value for MLRootPath for this tutorial is /greengrass/v2/work/
variant.TensorFlowLite/greengrass_ml. The greengrass_ml_tflite_venv folder in
this location is created when you deploy the inference component for the first time in Tutorial:
Perform sample image classification inference using TensorFlow Lite (p. 729).
Jetson Nano (Armv8)
1. Run the following command to test the camera setup.
gst-launch-1.0 nvarguscamerasrc num-buffers=1 ! "video/x-raw(memory:NVMM),
width=1920, height=1080, format=NV12, framerate=30/1" ! nvjpegenc ! filesink
location=test.jpg
This captures and saves an image named test.jpg to your current directory.
2. (Optional) Reboot the device. If you encounter issues when you run the gst-launch command
in the previous step, rebooting your device might resolve those issues.
sudo reboot
Note
For Armv8 (AArch64) devices, such as a Jetson Nano, you don't need to create a symlink to
enable the inference component to access the camera from the virtual environment that is
created by the runtime component.
AWS DeepLens (x86_64)
1. Update the awscam APT package. Run the following command on the device.
sudo apt-get update && sudo apt-get install awscam
2. Reboot the device.
sudo reboot
3. Run each of the following commands to create a symlink to enable the inference component to
access your camera from the virtual environment that is created by the runtime component.
sudo ln -s /usr/lib/python3/dist-packages/awscam "MLRootPath/
greengrass_ml_tflite_conda/envs/greengrass_ml_tflite_conda/lib/python3.7/site-
packages/"
735
AWS IoT Greengrass Developer Guide, Version 2
Step 2: Verify your subscription
to the default notifications topic
sudo ln -s /usr/lib/python3/dist-packages/awscamdldt.so "MLRootPath/
greengrass_ml_tflite_conda/envs/greengrass_ml_tflite_conda/lib/python3.7/site-
packages/"
The default value for MLRootPath for this tutorial is /greengrass/v2/work/
variant.TensorFlowLite/greengrass_ml. The greengrass_ml_tflite_conda folder
in this location is created when you deploy the inference component for the first time in
Tutorial: Perform sample image classification inference using TensorFlow Lite (p. 729).
For more information about using AWS DeepLens, see AWS DeepLens Developer Guide.
Step 2: Verify your subscription to the default
notifications topic
In Tutorial: Perform sample image classification inference using TensorFlow Lite (p. 729), you
configured the AWS IoT MQTT client is configured in the AWS IoT console to watch MQTT messages
published by the TensorFlow Lite image classification component on the ml/tflite/image-
classification topic. In the AWS IoT console, verify that this subscription exists. If it doesn't, follow
the steps in Step 1: Subscribe to the default notifications topic (p. 730) to subscribe to this topic before
you deploy the component to your Greengrass core device.
Step 3: Modify the TensorFlow Lite image
classification component configuration and deploy it
In this step, you configure and deploy the TensorFlow Lite image classification component to your core
device:
To configure and deploy the TensorFlow Lite image classification component
(console)
1. In the AWS IoT Greengrass console navigation menu, choose Components.
2. On the Components page, on the Public components tab, choose
aws.greengrass.TensorFlowLiteImageClassification.
3. On the aws.greengrass.TensorFlowLiteImageClassification page, choose Deploy.
4. From Add to deployment, choose one of the following:
a. To merge this component to an existing deployment on your target device, choose Add to
existing deployment, and then select the deployment that you want to revise.
b. To create a new deployment on your target device, choose Create new deployment. If you have
an existing deployment on your device, choosing this step replaces the existing deployment.
5. On the Specify target page, do the following:
a. Under Deployment information, enter or modify the friendly name for your deployment.
b. Under Deployment targets, select a target for your deployment, and choose Next. You cannot
change the deployment target if you are revising an existing deployment.
6. On the Select components page, under Public components, verify that the
aws.greengrass.TensorFlowLiteImageClassification component is selected, and choose
Next.
7. On the Configure components page, do the following:
736
AWS IoT Greengrass Developer Guide, Version 2
Step 3: Modify the TensorFlow Lite image
classification component configuration and deploy it
a. Select the inference component, and choose Configure component.
b. Under Configuration update, enter the following configuration update in the Configuration to
merge box.
{
"InferenceInterval": "60",
"UseCamera": "true"
}
With this configuration update, the component accesses the camera module on your device and
performs inference on images taken by the camera. The inference code runs every 60 seconds.
c. Choose Confirm, and then choose Next.
8. On the Configure advanced settings page, keep the default configuration settings, and choose
Next.
9. On the Review page, choose Deploy
To configure and deploy the TensorFlow Lite image classification component
(AWS CLI)
1. Create a deployment.json file to define the deployment configuration for the TensorFlow Lite
image classification component. This file should look like the following:
{
"targetArn":"targetArn",
"components": {
"aws.greengrass.TensorFlowLiteImageClassification": {
"componentVersion": 2.1.0,
"configurationUpdate": {
"InferenceInterval": "60",
"UseCamera": "true"
}
}
}
}
• In the targetArn field, replace targetArn with the Amazon Resource Name (ARN) of the thing
or thing group to target for the deployment, in the following format:
• Thing: arn:aws:iot:region:account-id:thing/thingName
• Thing group: arn:aws:iot:region:account-id:thinggroup/thingGroupName
• This tutorial uses component version 2.1.0. In the
aws.greengrass.TensorFlowLiteImageClassification component object, replace 2.1.0
to use a different version of the TensorFlow Lite image classification component.
With this configuration update, the component accesses the camera module on your device and
performs inference on images taken by the camera. The inference code runs every 60 seconds.
Replace the following values
2. Run the following command to deploy the TensorFlow Lite image classification component on the
device:
$ aws greengrassv2 create-deployment \
--cli-input-json file://path/to/deployment.json
737
AWS IoT Greengrass Developer Guide, Version 2
Step 4: View inference results
The deployment can take several minutes to complete. In the next step, check the component log to
verify that the deployment completed successfully and to view the inference results.
Step 4: View inference results
After you deploy the component, you can view the inference results in the component log on your
Greengrass core device and in the AWS IoT MQTT client in the AWS IoT console. To subscribe to the topic
on which the component publishes inference results, see Step 2: Verify your subscription to the default
notifications topic (p. 736).
• AWS IoT MQTT client—To view the results that the inference component publishes on the default
notifications topic (p. 730), complete the following steps:
1. In the AWS IoT console navigation menu, choose Test, MQTT test client.
2. Under Subscriptions, choose ml/tflite/image-classification.
• Component log—To view the inference results in the component log, run the following command on
your Greengrass core device.
sudo tail -f /greengrass/v2/logs/aws.greengrass.TensorFlowLiteImageClassification.log
If you can't see inference results in the component log or in the MQTT client, the deployment failed or
didn't reach the core device. This can occur if your core device isn't connected to the internet or doesn't
have the required permissions to run the component. Run the following command on your core device
to view the AWS IoT Greengrass Core software log file. This file includes logs from the Greengrass core
device's deployment service.
sudo tail -f /greengrass/v2/logs/greengrass.log
For more information, see Troubleshooting machine learning inference (p. 757).
Next steps
This tutorial shows you how to use the TensorFlow Lite image classification component, with custom
configuration options to perform sample image classification on images taken by a camera.
For more information about customizing the configuration of public components or creating custom
machine learning components, see Customize your machine learning components (p. 746).
Use Amazon SageMaker Edge Manager on
Greengrass core devices
Amazon SageMaker Edge Manager is a software agent that runs on edge devices. SageMaker Edge
Manager provides model management for edge devices so that you can package and use Amazon
SageMaker Neo-compiled models directly on Greengrass core devices. By using SageMaker Edge
Manager, you can also sample model input and output data from your core devices, and send that data
to the AWS Cloud for monitoring and analysis. Because SageMaker Edge Manager uses SageMaker Neo
to optimize your models for your target hardware, you don't need to install the DLR runtime directly on
your device. On Greengrass devices, SageMaker Edge Manager doesn't load local AWS IoT certificates or
738
AWS IoT Greengrass Developer Guide, Version 2
How it works
call the AWS IoT credential provider endpoint directly. Instead, SageMaker Edge Manager uses the token
exchange service (p. 407) to fetch temporary credential from a TES endpoint.
This section describes how SageMaker Edge Manager works on Greengrass devices. It shows you how
to get started using SageMaker Edge Manager with AWS-provided sample components on an existing
core device. These sample components use the SageMaker Edge Manager component as a dependency
to deploy the Edge Manager agent, and perform inference using pre-trained models that were compiled
using SageMaker Neo. For more information about the SageMaker Edge Manager agent, see SageMaker
Edge Manager in the Amazon SageMaker Developer Guide.
How SageMaker Edge Manager works on Greengrass
devices
To deploy the SageMaker Edge Manager agent to your core devices, create a deployment that includes
the aws.greengrass.SageMakerEdgeManager component. AWS IoT Greengrass manages the
installation and lifecycle of the Edge Manager agent on your devices. When a new version of the agent
binary is available, deploy the updated version of the aws.greengrass.SageMakerEdgeManager
component to upgrade the version of the agent that is installed on your device.
When you use SageMaker Edge Manager with AWS IoT Greengrass, your workflow includes the following
high-level steps:
1. Compile models with SageMaker Neo.
2. Package your SageMaker Neo-compiled models using SageMaker edge packaging jobs. When you
run an edge packaging job for your model, you can choose to create a model component with the
packaged model as an artifact that can be deployed to your Greengrass core device.
3. Create a custom inference component. You use this inference component to interact with the Edge
Manager agent to perform inference on the core device. These operations include loading models,
invoke prediction requests to run inference, and unloading models when the component shuts down.
4. Deploy the SageMaker Edge Manager component, the packaged model component, and the inference
component to run your model on the SageMaker inference engine (Edge Manager agent) on your
device.
For more information about creating edge packaging jobs and inference components that work with
SageMaker Edge Manager, see Create AWS IoT Greengrass V2 Components in the Amazon SageMaker
Developer Guide.
The Get started with SageMaker Edge Manager (p. 740) tutorial shows you how to set up and use the
SageMaker Edge Manager agent on an existing Greengrass core device, using AWS-provided example
code that you can use to create sample inference and model components.
When you use SageMaker Edge Manager on Greengrass core devices, you can also use the capture data
feature to upload sample data to the AWS Cloud. Capture data is a SageMaker feature that you use
to upload inference input, inference results, and additional inference data to an S3 bucket or a local
directory for future analysis. For more information about using capture data with SageMaker Edge
Manager, see Manage Model in the Amazon SageMaker Developer Guide.
Requirements
You must meet the following requirements to use the SageMaker Edge Manager agent on Greengrass
core devices.
• A Greengrass core device running on Amazon Linux 2, a Debian-based Linux platform (x86_64 or
Armv8), or Windows (x86_64). If you don't have one, see Getting started with AWS IoT Greengrass
V2 (p. 31).
739
AWS IoT Greengrass Developer Guide, Version 2
Get started with SageMaker Edge Manager
• Python 3.6 or later, including pip for your version of Python, installed on your core device.
• The Greengrass device role (p. 790) configured with the following:
• A trust relationship that allows credentials.iot.amazonaws.com and
sagemaker.amazonaws.com to assume the role, as shown in the following IAM policy example.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "credentials.iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
},
{
"Effect": "Allow",
"Principal": {
"Service": "sagemaker.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
• The AmazonSageMakerEdgeDeviceFleetPolicy IAM managed policy.
• The s3:PutObject action, as shown in the following IAM policy example.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"s3:PutObject"
],
"Resource": [
"*"
],
"Effect": "Allow"
}
]
}
• An Amazon S3 bucket created in the same AWS account and AWS Region as your Greengrass core
device. SageMaker Edge Manager requires an S3 bucket to create an edge device fleet, and to store
sample data from running inference on your device. For information about creating S3 buckets, see
Getting started with Amazon S3.
• A SageMaker edge device fleet that uses the same AWS IoT role alias as your Greengrass core device.
For more information, see Create an edge device fleet (p. 742).
• Your Greengrass core device registered as an edge device in your SageMaker Edge device fleet. The
edge device name must match the AWS IoT thing name for your core device. For more information, see
Register your Greengrass core device (p. 743).
Get started with SageMaker Edge Manager
To set up and use the SageMaker Edge Manager agent on an existing Greengrass core device,
AWS provides example code that you can use to create the following sample inference and model
components.
740
AWS IoT Greengrass Developer Guide, Version 2
Get started with SageMaker Edge Manager
• Image classification
• com.greengrass.SageMakerEdgeManager.ImageClassification
• com.greengrass.SageMakerEdgeManager.ImageClassification.Model
• Object detection
• com.greengrass.SageMakerEdgeManager.ObjectDetection
• com.greengrass.SageMakerEdgeManager.ObjectDetection.Model
This tutorial shows you how to deploy the sample components and the SageMaker Edge Manager agent.
Topics
• Prerequisites (p. 741)
• Set up your Greengrass core device in SageMaker Edge Manager (p. 742)
• Create the sample components (p. 743)
• Run sample image classification inference (p. 744)
Prerequisites
To complete this tutorial, you must meet the following prerequisites:
• A Greengrass core device running on Amazon Linux 2, a Debian-based Linux platform (x86_64 or
Armv8), or Windows (x86_64). If you don't have one, see Getting started with AWS IoT Greengrass
V2 (p. 31).
• Python 3.6 or later, including pip for your version of Python, installed on your core device.
• The OpenGL API GLX runtime (libgl1-mesa-glx) installed on your core device.
• An AWS Identity and Access Management (IAM) user with administrator permissions.
• An internet-enabled Windows, Mac, or Unix-like development computer that meets the following
requirements:
• Python 3.6 or later installed.
• AWS CLI installed and configured with your IAM administrator user credentials. For more
information, see Installing the AWS CLI and Configuring the AWS CLI.
• The following S3 buckets created in the same AWS account and AWS Region as your Greengrass core
device:
• An S3 bucket to store the artifacts that are included in the sample inference and model components.
This tutorial uses DOC-EXAMPLE-BUCKET1 to refer to this bucket.
• An S3 bucket that you associate with your SageMaker edge device fleet. SageMaker Edge Manager
requires an S3 bucket to create the edge device fleet, and to store sample data from running
inference on your device. This tutorial uses DOC-EXAMPLE-BUCKET2 to refer to this bucket.
For information about creating S3 buckets, see Getting started with Amazon S3.
• The Greengrass device role (p. 790) configured with the following:
• A trust relationship that allows credentials.iot.amazonaws.com and
sagemaker.amazonaws.com to assume the role, as shown in the following IAM policy example.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "credentials.iot.amazonaws.com"
741
AWS IoT Greengrass Developer Guide, Version 2
Get started with SageMaker Edge Manager
},
"Action": "sts:AssumeRole"
},
{
"Effect": "Allow",
"Principal": {
"Service": "sagemaker.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
• The AmazonSageMakerEdgeDeviceFleetPolicy IAM managed policy.
• The AmazonSageMakerFullAccess IAM managed policy.
• The s3:GetObject action for the S3 bucket that contains your component artifacts, as shown in
the following IAM policy example.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::DOC-EXAMPLE-BUCKET1/*"
],
"Effect": "Allow"
}
]
}
Set up your Greengrass core device in SageMaker Edge Manager
Edge device fleets in SageMaker Edge Manager are collections of logically grouped devices. To use
SageMaker Edge Manager with AWS IoT Greengrass, you must create an edge device fleet that uses the
same AWS IoT role alias as the Greengrass core device to which you deploy the SageMaker Edge Manager
agent. Then, you must register the core device as part of that fleet.
Topics
• Create an edge device fleet (p. 742)
• Register your Greengrass core device (p. 743)
Create an edge device fleet
To create an edge device fleet (console)
1. In the Amazon SageMaker console, choose Edge Manager, and then choose Edge device fleets.
2. On the Device fleets page, choose Create device fleet.
3. Under Device fleet properties, do the following:
• For Device fleet name, enter a name for your device fleet.
• For IAM role, enter the Amazon Resource Name (ARN) of the AWS IoT role alias that you specified
when setting up your Greengrass core device.
• Disable the Create IAM role alias toggle.
742
AWS IoT Greengrass Developer Guide, Version 2
Get started with SageMaker Edge Manager
4. Choose Next.
5. Under Output configuration, for S3 bucket URI, enter the URI of the S3 bucket that you want to
associate with the device fleet.
6. Choose Submit.
Register your Greengrass core device
To register your Greengrass core device as an edge device (console)
1. In the Amazon SageMaker console, choose Edge Manager, and then choose Edge devices.
2. On the Devices page, choose Register devices.
3. Under Device properties, for Device fleet name, enter the name of the device fleet that you
created, and then choose Next.
4. Choose Next.
5. Under Device source, for Device name, enter the AWS IoT thing name of your Greengrass core
device.
6. Choose Submit.
Create the sample components
To help you get started using the SageMaker Edge Manager component, AWS provides a Python script
on GitHub that creates the sample inference and model components and uploads them to the AWS
Cloud for you. Complete the following steps on a development computer.
To create the sample components
1. Download the AWS IoT Greengrass component examples repository on GitHub to your development
computer.
2. Navigate to the downloaded /machine-learning/sagemaker-edge-manager folder.
cd download-directory/machine-learning/sagemaker-edge-manager
3. Run the following command to create and upload the sample components to the AWS Cloud.
python3 create_components.py -r region -b DOC-EXAMPLE-BUCKET
Replace region with the AWS Region where you created your Greengrass core device, and replace
DOC-EXAMPLE-BUCKET1 with the name of the S3 bucket to store your component artifacts.
Note
By default, the script creates sample components for both image classification and object
detection inference. To create components for only a specific type of inference, specify the
-i ImageClassification | ObjectDetection argument.
Sample inference and model components for use with SageMaker Edge Manager are now created in your
AWS account. To see the sample components in the AWS IoT Greengrass console, choose Components,
and then under My components, search for the following components:
• com.greengrass.SageMakerEdgeManager.ImageClassification
• com.greengrass.SageMakerEdgeManager.ImageClassification.Model
• com.greengrass.SageMakerEdgeManager.ObjectDetection
743
AWS IoT Greengrass Developer Guide, Version 2
Get started with SageMaker Edge Manager
• com.greengrass.SageMakerEdgeManager.ObjectDetection.Model
Run sample image classification inference
To run image classification inference using the AWS-provided sample components and the SageMaker
Edge Manager agent, you must deploy these components to your core device. Deploying these
components downloads a SageMaker Neo-compiled pre-trained Resnet-50 model and installs the
SageMaker Edge Manager agent on your device. The SageMaker Edge Manager agent loads the model
and publishes inference results on the gg/sageMakerEdgeManager/image-classification topic.
To view these inference results, use the AWS IoT MQTT client in the AWS IoT console to subscribe to this
topic.
Topics
• Subscribe to the notifications topic (p. 744)
• Deploy the sample components (p. 744)
• View inference results (p. 746)
Subscribe to the notifications topic
In this step, you configure the AWS IoT MQTT client in the AWS IoT console to watch MQTT messages
published by the sample inference component. By default, the component publishes inference results on
the gg/sageMakerEdgeManager/image-classification topic. Subscribe to this topic before you
deploy the component to your Greengrass core device to see the inference results when the component
runs for the first time.
To subscribe to the default notifications topic
1. In the AWS IoT console navigation menu, choose Test, MQTT test client.
2. Under Subscribe to a topic, in the Topic name box, enter gg/sageMakerEdgeManager/image-
classification.
3. Choose Subscribe.
Deploy the sample components
In this step, you configure and deploy the following components to your core device:
• aws.greengrass.SageMakerEdgeManager
• com.greengrass.SageMakerEdgeManager.ImageClassification
• com.greengrass.SageMakerEdgeManager.ImageClassification.Model
To deploy your components (console)
1. In the AWS IoT Greengrass console navigation menu, choose Deployments, and then choose the
deployment for your target device that you want to revise.
2. On the deployment page, choose Revise, and then choose Revise deployment.
3. On the Specify target page, choose Next.
4. On the Select components page, do the following:
a. Under My components, select the following components:
• com.greengrass.SageMakerEdgeManager.ImageClassification
744
AWS IoT Greengrass Developer Guide, Version 2
Get started with SageMaker Edge Manager
• com.greengrass.SageMakerEdgeManager.ImageClassification.Model
b. Under Public components, turn off the Show only selected components toggle, and then
select the aws.greengrass.SageMakerEdgeManager component.
c. Choose Next.
5. On the Configure components page, select the aws.greengrass.SageMakerEdgeManager
component and do the following.
a. Choose Configure component.
b. Under Configuration update, in Configuration to merge, enter the following configuration.
{
"DeviceFleetName": "device-fleet-name",
"BucketName": "DOC-EXAMPLE-BUCKET"
}
Replace device-fleet-name with the name of the edge device fleet that you created, and
replace DOC-EXAMPLE-BUCKET with the name of the S3 bucket that is associated with your
device fleet.
c. Choose Confirm, and then choose Next.
6. On the Configure advanced settings page, keep the default configuration settings, and choose
Next.
7. On the Review page, choose Deploy
To deploy your components (AWS CLI)
1. On your development computer, create a deployment.json file to define the deployment
configuration for your SageMaker Edge Manager components. This file should look like the following
example.
{
"targetArn":"targetArn",
"components": {
"aws.greengrass.SageMakerEdgeManager": {
"componentVersion": "1.0.x",
"configurationUpdate": {
"merge": "{\"DeviceFleetName\":\"device-fleet-name\",\"BucketName\":\"DOC-
EXAMPLE-BUCKET2\"}"
}
},
"com.greengrass.SageMakerEdgeManager.ImageClassification": {
"componentVersion": "1.0.x",
"configurationUpdate": {
}
},
"com.greengrass.SageMakerEdgeManager.ImageClassification.Model": {
"componentVersion": "1.0.x",
"configurationUpdate": {
}
},
}
}
• In the targetArn field, replace targetArn with the Amazon Resource Name (ARN) of the thing
or thing group to target for the deployment, in the following format:
• Thing: arn:aws:iot:region:account-id:thing/thingName
• Thing group: arn:aws:iot:region:account-id:thinggroup/thingGroupName
745
AWS IoT Greengrass Developer Guide, Version 2
Customize your machine learning components
• In the merge field, replace device-fleet-name with the name of the edge device fleet that you
created. Then, replace DOC-EXAMPLE-BUCKET2 with the name of the S3 bucket that is associated
with your device fleet.
• Replace the component versions for each component with the latest available version.
2. Run the following command to deploy the components on the device:
$ aws greengrassv2 create-deployment \
--cli-input-json file://path/to/deployment.json
The deployment can take several minutes to complete. In the next step, check the component log to
verify that the deployment completed successfully and to view the inference results.
View inference results
After you deploy the components, you can view the inference results in the component log on your
Greengrass core device and in the AWS IoT MQTT client in the AWS IoT console. To subscribe to the topic
on which the component publishes inference results, see Subscribe to the notifications topic (p. 744).
• AWS IoT MQTT client—To view the results that the inference component publishes on the default
notifications topic (p. 744), complete the following steps:
1. In the AWS IoT console navigation menu, choose Test, MQTT test client.
2. Under Subscriptions, choose gg/sageMakerEdgeManager/image-classification.
• Component log—To view the inference results in the component log, run the following command on
your Greengrass core device.
sudo tail -f /greengrass/v2/logs/
com.greengrass.SageMakerEdgeManager.ImageClassification.log
If you can't see inference results in the component log or in the MQTT client, the deployment failed or
didn't reach the core device. This can occur if your core device isn't connected to the internet or doesn't
have the right permissions to run the component. Run the following command on your core device to
view the AWS IoT Greengrass Core software log file. This file includes logs from the Greengrass core
device's deployment service.
sudo tail -f /greengrass/v2/logs/greengrass.log
For more information, see Troubleshooting machine learning inference (p. 757).
Customize your machine learning components
In AWS IoT Greengrass, you can configure sample machine learning components (p. 725) to customize
how you perform machine learning inference on your devices with the inference, model, and runtime
components as the building blocks. AWS IoT Greengrass also provides you the flexibility to use the
sample components as templates and create your own custom components as needed. You can mix and
match this modular approach to customize your machine learning inference components in the following
ways:
746
AWS IoT Greengrass Developer Guide, Version 2
Modify the configuration of a public inference component
Using sample inference components
• Modify the configuration of inference components when you deploy them.
• Use a custom model with the sample inference component by replacing the sample model store
component with a custom model component. Your custom model must be trained using the same
runtime as the sample model.
Using custom inference components
• Use custom inference code with the sample models and runtimes by adding public model
components and runtime components as dependencies of custom inference components.
• Create and add custom model components or runtime components as dependencies of custom
inference components. You must use custom components if you want to use custom inference
code or a runtime for which AWS IoT Greengrass doesn't provide a sample component.
Topics
• Modify the configuration of a public inference component (p. 747)
• Use a custom model with the sample inference component (p. 748)
• Create custom machine learning components (p. 751)
• Create a custom inference component (p. 753)
Modify the configuration of a public inference
component
In the AWS IoT Greengrass console, the component page displays the default configuration of that
component. For example, the default configuration of the TensorFlow Lite image classification
component looks like the following:
{
"accessControl": {
"aws.greengrass.ipc.mqttproxy": {
"aws.greengrass.TensorFlowLiteImageClassification:mqttproxy:1": {
"policyDescription": "Allows access to publish via topic ml/tflite/image-
classification.",
"operations": [
"aws.greengrass#PublishToIoTCore"
],
"resources": [
"ml/tflite/image-classification"
]
}
}
},
"PublishResultsOnTopic": "ml/tflite/image-classification",
"ImageName": "cat.jpeg",
"InferenceInterval": 3600,
"ModelResourceKey": {
"model": "TensorFlowLite-Mobilenet"
}
}
When you deploy a public inference component, you can modify the default configuration to customize
your deployment. For information about the available configuration parameters for each public inference
component, see the component topic in AWS-provided machine learning components (p. 725).
This section describes how to deploy a modified component from the AWS IoT Greengrass console. For
information about deploying components using the AWS CLI, see Create deployments (p. 493).
747
AWS IoT Greengrass Developer Guide, Version 2
Use a custom model with the sample inference component
To deploy a modified public inference component (console)
1. Sign in to the AWS IoT Greengrass console.
2. In the navigation menu, choose Components.
3. On the Components page, on the Public components tab, choose the component you want to
deploy.
4. On the component page, choose Deploy.
5. From Add to deployment, choose one of the following:
a. To merge this component to an existing deployment on your target device, choose Add to
existing deployment, and then select the deployment that you want to revise.
b. To create a new deployment on your target device, choose Create new deployment. If you have
an existing deployment on your device, choosing this step replaces the existing deployment.
6. On the Specify target page, do the following:
a. Under Deployment information, enter or modify the friendly name for your deployment.
b. Under Deployment targets, select a target for your deployment, and choose Next. You cannot
change the deployment target if you are revising an existing deployment.
7. On the Select components page, under Public components verify that the inference component
with your modified configuration is selected, and choose Next.
8. On the Configure components page, do the following:
a. Select the inference component, and choose Configure component.
b. Under Configuration update, enter the configuration values that you want to update. For
example, enter the following configuration update in the Configuration to merge box to
change the inference interval to 15 seconds, and instruct the component to look for the image
named custom.jpg in the /custom-ml-inference/images/ folder.
{
"InferenceInterval": "15",
"ImageName": "custom.jpg",
"ImageDirectory": "/custom-ml-inference/images/"
}
To reset a component's entire configuration to its default values, specify a single empty string
"" in the Reset paths box.
c. Choose Confirm, and then choose Next.
9. On the Configure advanced setting page, keep the default configuration settings, and choose Next.
10. On the Review page, choose Deploy
Use a custom model with the sample inference
component
If you want to use the sample inference component with your own machine learning models for a
runtime for which AWS IoT Greengrass provides a sample runtime component, you must override the
public model components with components that use those models as artifacts. At a high-level you
complete the following steps to use a custom model with the sample inference component:
1. Create a model component that uses a custom model in an S3 bucket as an artifact. Your custom
model must be trained using the same runtime as the model that you want to replace.
748
AWS IoT Greengrass Developer Guide, Version 2
Use a custom model with the sample inference component
2. Modify the ModelResourceKey configuration parameter in the inference component to use the
custom model. For information about updating the configuration of the inference component, see
Modify the configuration of a public inference component (p. 747)
When you deploy the inference component, AWS IoT Greengrass looks for the latest version of its
component dependencies. It overrides the dependent public model component if a later custom version
of the component exists in the same AWS account and AWS Region.
Create a custom model component (console)
1. Upload your model to an S3 bucket. For information about uploading your models to an S3 bucket,
see Working with Amazon S3 Buckets in the Amazon Simple Storage Service User Guide.
Note
You must store your artifacts in S3 buckets that are in the same AWS account and AWS
Region as the components. To enable AWS IoT Greengrass to access these artifacts,
the Greengrass device role (p. 790) must allow the s3:GetObject action. For more
information about the device role, see Authorize core devices to interact with AWS
services (p. 790).
2. In the AWS IoT Greengrass console navigation menu, choose Components.
3. Retrieve the component recipe for the public model store component.
a. On the Components page, on the Public components tab, look for and choose the
public model component for which you want to create a new version. For example,
variant.DLR.ImageClassification.ModelStore.
b. On the component page, choose View recipe and copy the displayed JSON recipe.
4. On the Components page, on the My components tab, choose Create component.
5. On the Create component page, under Component information, select Enter recipe as JSON as
your component source.
6. In the Recipe box, paste the component recipe that you previously copied.
7. In the recipe, update the following values:
• ComponentVersion: Increment the minor version of the component.
When you create a custom component to override a public model component, you must update
only the minor version of the existing component version. For example, if the public component
version is 2.1.0, you can create a custom component with version 2.1.1.
• Manifests.Artifacts.Uri: Update each URI value to the Amazon S3 URI of the model that
you want to use.
Note
Do not change the name of the component.
8. Choose Create component.
Create a custom model component (AWS CLI)
1. Upload your model to an S3 bucket. For information about uploading your models to an S3 bucket,
see Working with Amazon S3 Buckets in the Amazon Simple Storage Service User Guide.
Note
You must store your artifacts in S3 buckets that are in the same AWS account and AWS
Region as the components. To enable AWS IoT Greengrass to access these artifacts,
the Greengrass device role (p. 790) must allow the s3:GetObject action. For more
749
AWS IoT Greengrass Developer Guide, Version 2
Use a custom model with the sample inference component
information about the device role, see Authorize core devices to interact with AWS
services (p. 790).
2. Run the following command to retrieve the component recipe of the public component. This
command writes the component recipe to the output file that you provide in your command.
Convert the retrieved base64-encoded string to JSON or YAML, as needed.
Linux, macOS, or Unix
aws greengrassv2 get-component \
--arn <arn> \
--recipe-output-format <recipe-format> \
--query recipe \
--output text | base64 --decode > <recipe-file>
Windows Command Prompt (CMD)
aws greengrassv2 get-component ^
--arn <arn> ^
--recipe-output-format <recipe-format> ^
--query recipe ^
--output text > <recipe-file>.base64
certutil -decode <recipe-file>.base64 <recipe-file>
PowerShell
aws greengrassv2 get-component `
--arn <arn> `
--recipe-output-format <recipe-format> `
--query recipe `
--output text > <recipe-file>.base64
certutil -decode <recipe-file>.base64 <recipe-file>
3. Update the name of the recipe file to <component-name>-<component-version>,
where component version is the target version of the new component. For example,
variant.DLR.ImageClassification.ModelStore-2.1.1.yaml.
4. In the recipe, update the following values:
• ComponentVersion: Increment the minor version of the component.
When you create a custom component to override a public model component, you must update
only the minor version of the existing component version. For example, if the public component
version is 2.1.0, you can create a custom component with version 2.1.1.
• Manifests.Artifacts.Uri: Update each URI value to the Amazon S3 URI of the model that
you want to use.
Note
Do not change the name of the component.
5. Run the following command to create a new component using the recipe you retrieved and
modified.
aws greengrassv2 create-component-version \
--inline-recipe fileb://path/to/component/recipe
750
AWS IoT Greengrass Developer Guide, Version 2
Create custom machine learning components
Note
This step creates the component in the AWS IoT Greengrass service in the AWS Cloud.
You can use the Greengrass CLI to develop, test, and deploy your component locally
before you upload it to the cloud. For more information, see Develop AWS IoT Greengrass
components (p. 440).
For more information about creating components, see Develop AWS IoT Greengrass
components (p. 440).
Create custom machine learning components
You must create custom components if you want to use custom inference code or a runtime for which
AWS IoT Greengrass doesn't provide a sample component. You can use your custom inference code with
the AWS-provided sample machine learning models and runtimes, or you can develop a completely
customized machine learning inference solution with your own models and runtime. If your models use
a runtime for which AWS IoT Greengrass provides a sample runtime component, then you can use that
runtime component, and you need to create custom components only for your inference code and the
models you want to use.
Topics
• Retrieve the recipe for a public component (p. 751)
• Retrieve sample component artifacts (p. 752)
• Upload component artifacts to an S3 bucket (p. 752)
• Create custom components (p. 752)
Retrieve the recipe for a public component
You can use the recipe of an existing public machine learning component as a template to create a
custom component. To view the component recipe for the latest version of a public component, use the
console or the AWS CLI as follows:
• Using the console
1. On the Components page, on the Public components tab, look for and choose the public
component.
2. On the component page, choose View recipe.
• Using AWS CLI
Run the following command to retrieve the component recipe of the public variant component. This
command writes the component recipe to the JSON or YAML recipe file that you provide in your
command.
Linux, macOS, or Unix
aws greengrassv2 get-component \
--arn <arn> \
--recipe-output-format <recipe-format> \
--query recipe \
--output text | base64 --decode > <recipe-file>
Windows Command Prompt (CMD)
aws greengrassv2 get-component ^
--arn <arn> ^
751
AWS IoT Greengrass Developer Guide, Version 2
Create custom machine learning components
--recipe-output-format <recipe-format> ^
--query recipe ^
--output text > <recipe-file>.base64
certutil -decode <recipe-file>.base64 <recipe-file>
PowerShell
aws greengrassv2 get-component `
--arn <arn> `
--recipe-output-format <recipe-format> `
--query recipe `
--output text > <recipe-file>.base64
certutil -decode <recipe-file>.base64 <recipe-file>
Replace the values in your command as follows:
• <arn>. The Amazon Resource Name (ARN) of the public component.
• <recipe-format>. The format in which you want to create the recipe file. Supported values are
JSON and YAML.
• <recipe-file>. The name of the recipe in the format <component-name>-<component-
version>.
Retrieve sample component artifacts
You can use the artifacts used by the public machine learning components as templates to create your
custom component artifacts, such as inference code or runtime installation scripts.
To view the sample artifacts that are included in the public machine learning components, deploy
the public inference component and then view the artifacts on your device in the /greengrass/v2/
packages/artifacts-unarchived/component-name/component-version/ folder.
Upload component artifacts to an S3 bucket
Before you can create a custom component, you must upload the component artifacts to an S3 bucket
and use the S3 URIs in your component recipe. For example, to use custom inference code in your
inference component, upload the code to an S3 bucket. You can then use the Amazon S3 URI of your
inference code as an artifact in your component.
For information about uploading content to an S3 bucket, see Working with Amazon S3 Buckets in the
Amazon Simple Storage Service User Guide.
Note
You must store your artifacts in S3 buckets that are in the same AWS account and AWS Region
as the components. To enable AWS IoT Greengrass to access these artifacts, the Greengrass
device role (p. 790) must allow the s3:GetObject action. For more information about the
device role, see Authorize core devices to interact with AWS services (p. 790).
Create custom components
You can use the artifacts and recipes that you retrieved to create your custom machine learning
components. For an example, see Create a custom inference component (p. 753).
For detailed information about creating and deploying components to Greengrass devices, see
Develop AWS IoT Greengrass components (p. 440) and Deploy AWS IoT Greengrass components to
devices (p. 491).
752
AWS IoT Greengrass Developer Guide, Version 2
Create a custom inference component
Create a custom inference component
This section shows you how to create a custom inference component using the DLR image classification
component as a template.
Topics
• Upload your inference code to an Amazon S3 bucket (p. 753)
• Create a recipe for your inference component (p. 753)
• Create the inference component (p. 757)
Upload your inference code to an Amazon S3 bucket
Create your inference code and then upload it to an S3 bucket. For information about uploading content
to an S3 bucket, see Working with Amazon S3 Buckets in the Amazon Simple Storage Service User Guide.
Note
You must store your artifacts in S3 buckets that are in the same AWS account and AWS Region
as the components. To enable AWS IoT Greengrass to access these artifacts, the Greengrass
device role (p. 790) must allow the s3:GetObject action. For more information about the
device role, see Authorize core devices to interact with AWS services (p. 790).
Create a recipe for your inference component
1. Run the following command to retrieve the component recipe of the DLR image classification
component. This command writes the component recipe to the JSON or YAML recipe file that you
provide in your command.
Linux, macOS, or Unix
aws greengrassv2 get-component \
--arn
arn:aws:greengrass:region:aws:components:aws.greengrass.DLRImageClassification:versions:version
\
--recipe-output-format JSON | YAML \
--query recipe \
--output text | base64 --decode > <recipe-file>
Windows Command Prompt (CMD)
aws greengrassv2 get-component ^
--arn
arn:aws:greengrass:region:aws:components:aws.greengrass.DLRImageClassification:versions:version
^
--recipe-output-format JSON | YAML ^
--query recipe ^
--output text > <recipe-file>.base64
certutil -decode <recipe-file>.base64 <recipe-file>
PowerShell
aws greengrassv2 get-component `
--arn
arn:aws:greengrass:region:aws:components:aws.greengrass.DLRImageClassification:versions:version
`
--recipe-output-format JSON | YAML `
753
AWS IoT Greengrass Developer Guide, Version 2
Create a custom inference component
--query recipe `
--output text > <recipe-file>.base64
certutil -decode <recipe-file>.base64 <recipe-file>
Replace <recipe-file> with the name of the recipe in the format <component-
name>-<component-version>.
2. In the ComponentDependencies object in your recipe, do one or more of the following depending
on the model and runtime components that you want to use:
• Keep the DLR component dependency if you want to use DLR-compiled models. You can also
replace it with a dependency on a custom runtime component, as shown in the following example.
Runtime component
JSON
{
"<runtime-component>": {
"VersionRequirement": "<version>",
"DependencyType": "HARD"
}
}
YAML
<runtime-component>:
VersionRequirement: "<version>"
DependencyType: HARD
• Keep the DLR image classification model store dependency to use the pre-trained ResNet-50
models that AWS provides, or modify it to use a custom model component. When you include
a dependency for a public model component, if a later custom version of the component exists
in the same AWS account and AWS Region, then the inference component uses that custom
component. Specify the model component dependency as shown in the following examples.
Public model component
JSON
{
"variant.DLR.ImageClassification.ModelStore": {
"VersionRequirement": "<version>",
"DependencyType": "HARD"
}
}
YAML
variant.DLR.ImageClassification.ModelStore:
VersionRequirement: "<version>"
DependencyType: HARD
Custom model component
JSON
{
"<custom-model-component>": {
754
AWS IoT Greengrass Developer Guide, Version 2
Create a custom inference component
"VersionRequirement": "<version>",
"DependencyType": "HARD"
}
}
YAML
<custom-model-component>:
VersionRequirement: "<version>"
DependencyType: HARD
3. In the ComponentConfiguration object, add the default configuration for this component. You
can later modify this configuration when you deploy the component. The following excerpt shows
the component configuration for the DLR image classification component.
For example, if you use a custom model component as a dependency for your custom inference
component, then modify ModelResourceKey to provide the names of the models that you are
using.
JSON
{
"accessControl": {
"aws.greengrass.ipc.mqttproxy": {
"aws.greengrass.ImageClassification:mqttproxy:1": {
"policyDescription": "Allows access to publish via topic ml/dlr/image-
classification.",
"operations": [
"aws.greengrass#PublishToIoTCore"
],
"resources": [
"ml/dlr/image-classification"
]
}
}
},
"PublishResultsOnTopic": "ml/dlr/image-classification",
"ImageName": "cat.jpeg",
"InferenceInterval": 3600,
"ModelResourceKey": {
"armv7l": "DLR-resnet50-armv7l-cpu-ImageClassification"
"x86_64": "DLR-resnet50-x86_64-cpu-ImageClassification"
"aarch64": "DLR-resnet50-aarch64-cpu-ImageClassification"
}
}
YAML
accessControl:
aws.greengrass.ipc.mqttproxy:
'aws.greengrass.ImageClassification:mqttproxy:1':
policyDescription: 'Allows access to publish via topic ml/dlr/image-
classification.'
operations:
- 'aws.greengrass#PublishToIoTCore'
resources:
- ml/dlr/image-classification
PublishResultsOnTopic: ml/dlr/image-classification
ImageName: cat.jpeg
InferenceInterval: 3600
ModelResourceKey:
armv7l: "DLR-resnet50-armv7l-cpu-ImageClassification"
755
AWS IoT Greengrass Developer Guide, Version 2
Create a custom inference component
x86_64: "DLR-resnet50-x86_64-cpu-ImageClassification"
aarch64: "DLR-resnet50-aarch64-cpu-ImageClassification"
4. In the Manifests object, provide information about the artifacts and the configuration of
this component that are used when the component is deployed to different platforms and any
other information required to successfully run the component. The following excerpt shows
the configuration of the Manifests object for Linux platform in the DLR image classification
component.
JSON
{
"Manifests": [
{
"Platform": {
"os": "linux",
"architecture": "arm"
},
"Name": "32-bit armv7l - Linux (raspberry pi)",
"Artifacts": [
{
"URI": "s3://SAMPLE-BUCKET/sample-artifacts-directory/
image_classification.zip",
"Unarchive": "ZIP"
}
],
"Lifecycle": {
"Setenv": {
"DLR_IC_MODEL_DIR":
"{variant.DLR.ImageClassification.ModelStore:artifacts:decompressedPath}/
{configuration:/ModelResourceKey/armv7l}",
"DEFAULT_DLR_IC_IMAGE_DIR": "{artifacts:decompressedPath}/
image_classification/sample_images/"
},
"Run": {
"RequiresPrivilege": true,
"script": ". {variant.DLR:configuration:/MLRootPath}/
greengrass_ml_dlr_venv/bin/activate\npython3 {artifacts:decompressedPath}/
image_classification/inference.py"
}
}
}
]
}
YAML
Manifests:
- Platform:
os: linux
architecture: arm
Name: 32-bit armv7l - Linux (raspberry pi)
Artifacts:
- URI: s3://SAMPLE-BUCKET/sample-artifacts-directory/image_classification.zip
Unarchive: ZIP
Lifecycle:
Setenv:
DLR_IC_MODEL_DIR:
"{variant.DLR.ImageClassification.ModelStore:artifacts:decompressedPath}/
{configuration:/ModelResourceKey/armv7l}"
DEFAULT_DLR_IC_IMAGE_DIR: "{artifacts:decompressedPath}/
image_classification/sample_images/"
Run:
756
AWS IoT Greengrass Developer Guide, Version 2
Troubleshooting
RequiresPrivilege: true
script: |-
. {variant.DLR:configuration:/MLRootPath}/greengrass_ml_dlr_venv/bin/
activate
python3 {artifacts:decompressedPath}/image_classification/inference.py
For detailed information about creating component recipes, see AWS IoT Greengrass component recipe
reference (p. 471).
Create the inference component
Use the AWS IoT Greengrass console or the AWS CLI to create a component using the recipe you just
defined. After you create the component, you can deploy it to perform inference on your device. For an
example of how to deploy an inference component, see Tutorial: Perform sample image classification
inference using TensorFlow Lite (p. 729).
Create custom inference component (console)
1. Sign in to the AWS IoT Greengrass console.
2. In the navigation menu, choose Components.
3. On the Components page, on the My components tab, choose Create component.
4. On the Create component page, under Component information, select either Enter recipe as JSON
or Enter recipe as YAML as your component source.
5. In the Recipe box, enter the custom recipe that you created.
6. Click Create component.
Create custom inference component (AWS CLI)
Run the following command to create a new custom component using the recipe that you created.
aws greengrassv2 create-component-version \
--inline-recipe fileb://path/to/recipe/file
Note
This step creates the component in the AWS IoT Greengrass service in the AWS Cloud. You can
use the Greengrass CLI to develop, test, and deploy your component locally before you upload it
to the cloud. For more information, see Develop AWS IoT Greengrass components (p. 440).
Troubleshooting machine learning inference
Use the troubleshooting information and solutions in this section to help resolve issues with your
machine learning components. For the public machine learning inference components, you can see error
messages in the following component logs:
Linux or Unix
• /greengrass/v2/logs/aws.greengrass.DLRImageClassification.log
• /greengrass/v2/logs/aws.greengrass.DLRObjectDetection.log
• /greengrass/v2/logs/aws.greengrass.TensorFlowLiteImageClassification.log
• /greengrass/v2/logs/aws.greengrass.TensorFlowLiteObjectDetection.log
757
AWS IoT Greengrass Developer Guide, Version 2
Failed to fetch library
Windows
• C:\greengrass\v2\logs\aws.greengrass.DLRImageClassification.log
• C:\greengrass\v2\logs\aws.greengrass.DLRObjectDetection.log
• C:\greengrass\v2\logs\aws.greengrass.TensorFlowLiteImageClassification.log
• C:\greengrass\v2\logs\aws.greengrass.TensorFlowLiteObjectDetection.log
If a component is installed correctly, then the component log contains the location of the library that it
uses for inference.
Issues
• Failed to fetch library (p. 758)
• Cannot open shared object file (p. 758)
• <library> not found (p. 758)
• No CUDA-capable device is detected (p. 759)
• No such file or directory (p. 759)
• Memory errors (p. 759)
• Disk space errors (p. 760)
• Timeout errors (p. 760)
Failed to fetch library
Te following error occurs when the installer script fails to download a required library during deployment
on a Raspberry Pi device.
Err:2 http://raspbian.raspberrypi.org/raspbian buster/main armhf python3.7-dev armhf
3.7.3-2+deb10u1
404 Not Found [IP: 93.93.128.193 80]
E: Failed to fetch http://raspbian.raspberrypi.org/raspbian/pool/main/p/python3.7/
libpython3.7-dev_3.7.3-2+deb10u1_armhf.deb 404 Not Found [IP: 93.93.128.193 80]
Run sudo apt-get update and deploy your component again.
Cannot open shared object file
You might see errors similar to the following when the installer script fails to download a required
dependency for opencv-python during deployment on a Raspberry Pi device.
ImportError: libopenjp2.so.7: cannot open shared object file: No such file or directory
Run the following command to manually install the dependencies for opencv-python:
sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-
dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
<library> not found
The following errors indicate that the runtime component was unable to set up the virtual environment
correctly:
758
AWS IoT Greengrass Developer Guide, Version 2
No CUDA-capable device is detected
• cv2 not found
• dlr not found
• numpy not found
Check the logs to make sure that all runtime dependencies were installed correctly. For more information
about the libraries installed by the installer script, see the following topics:
• DLR installer (p. 319)
• TensorFlow Lite installer (p. 339)
No CUDA-capable device is detected
You might see the following error when you use GPU acceleration. Run the following command to enable
GPU access for the Greengrass user.
sudo usermod -a -G video ggc_user
No such file or directory
The following errors indicate that the runtime component was unable to set up the virtual environment
correctly:
• MLRootPath/greengrass_ml_dlr_conda/bin/conda: No such file or directory
• MLRootPath/greengrass_ml_dlr_venv/bin/activate: No such file or directory
• MLRootPath/greengrass_ml_tflite_conda/bin/conda: No such file or directory
• MLRootPath/greengrass_ml_tflite_venv/bin/activate: No such file or directory
Check the logs to make sure that all runtime dependencies were installed correctly. For more information
about the libraries installed by the installer script, see the following topics:
• DLR installer (p. 319)
• TensorFlow Lite installer (p. 339)
By default MLRootPath is set to /greengrass/v2/work/component-name/greengrass_ml. To
change this location, include the DLR installer (p. 319) or TensorFlow Lite installer (p. 339) runtime
component directly in your deployment, and specify a modified value for the MLRootPath parameter
in a configuration merge update. For more information about configuring component, see Update
component configurations (p. 500).
Note
For the DLR component v1.3.x, you set the MLRootPath parameter in the configuration of the
inference component, and the default value is $HOME/greengrass_ml.
Memory errors
The following errors typically occur when the device does not have enough memory and the component
process is interrupted.
• stderr. Killed.
• exitCode=137
759
AWS IoT Greengrass Developer Guide, Version 2
Disk space errors
We recommend a minimum of 500 MB of memory to deploy a public machine learning inference
component.
Disk space errors
The no space left on device error typically occurs when a device does not have enough storage.
Check the disk space that is available on your device and make sure you have enough space before you
deploy the component again. We recommend a minimum of 500 MB of free disk space to deploy a public
machine learning inference component.
Timeout errors
The public machine learning components download large machine learning model files that are larger
than 200 MB. If the download times out during deployment, check your internet connection speed and
retry the deployment.
760
AWS IoT Greengrass Developer Guide, Version 2
Install the Systems Manager Agent
Manage Greengrass core devices
with AWS Systems Manager
Note
AWS IoT Greengrass doesn't currently support this feature on Windows core devices.
Systems Manager is an AWS service that you can use to view and control your infrastructure on AWS,
including Amazon EC2 instances, on-premises servers and virtual machines (VMs), and edge devices.
Systems Manager enables you to view operational data, automate operation tasks, and maintain security
and compliance. When you register a machine with Systems Manager, it's called a managed node. For
more information, see What is AWS Systems Manager? in the AWS Systems Manager User Guide.
The AWS Systems Manager Agent (Systems Manager Agent) is software that you can install on devices
to enable Systems Manager to update, manage, and configure them. To install the Systems Manager
Agent on Greengrass core devices, deploy the Systems Manager Agent component (p. 403). When you
deploy the Systems Manager Agent for the first time, it registers the core device as a Systems Manager
managed node. The Systems Manager Agent runs on the device to enable communication with the
Systems Manager service in the AWS Cloud. For more information about how to install and configure the
Systems Manager Agent component, see Install the AWS Systems Manager Agent (p. 761).
Systems Manager tools and features are called capabilities. Greengrass core devices support all Systems
Manager capabilities. For more information about these capabilities and how to use Systems Manager to
manage core devices, see Systems Manager capabilities in the AWS Systems Manager User Guide.
AWS Systems Manager offers a standard-instances tier and an advanced-instances tier for Systems
Manager managed nodes. If you're using Systems Manager for the first time, you start on the standard-
instances tier. On the standard-instances tier, you can register up to 1,000 managed nodes per AWS
Region in your AWS account. If you need to register more than 1,000 managed nodes in a single account
and Region, or if you need to use the Session Manager capability, use the advanced-instances tier. For
more information, see Configuring instance tiers in the AWS Systems Manager User Guide.
Topics
• Install the AWS Systems Manager Agent (p. 761)
• Uninstall the AWS Systems Manager Agent (p. 768)
Install the AWS Systems Manager Agent
The AWS Systems Manager Agent (Systems Manager Agent) is Amazon software that you install to
enable Systems Manager to update, manage, and configure Greengrass core devices, Amazon EC2
instances, and other resources. The agent processes and runs requests from the Systems Manager service
in the AWS Cloud. Then, the agent sends status and runtime information back to the Systems Manager
service. For more information, see About Systems Manager Agent in the AWS Systems Manager User
Guide.
AWS provides the Systems Manager Agent as a Greengrass component that you can deploy to your
Greengrass core devices to manage them with Systems Manager. The Systems Manager Agent
component (p. 403) installs the Systems Manager Agent software and registers the core device as a
managed node in Systems Manager. Follow the steps on this page to complete prerequisites and deploy
the Systems Manager Agent component to a core device or group of core devices.
761
AWS IoT Greengrass Developer Guide, Version 2
Step 1: Complete general Systems Manager setup steps
Topics
• Step 1: Complete general Systems Manager setup steps (p. 762)
• Step 2: Create an IAM service role for Systems Manager (p. 762)
• Step 3: Add permissions to the token exchange role (p. 762)
• Step 4: Deploy the Systems Manager Agent component (p. 765)
• Step 5: Verify core device registration with Systems Manager (p. 767)
Step 1: Complete general Systems Manager setup
steps
If you haven't already done so, complete general setup steps for AWS Systems Manager. For more
information, see Complete general Systems Manager setup steps in the AWS Systems Manager User
Guide.
Step 2: Create an IAM service role for Systems
Manager
The Systems Manager Agent uses an AWS Identity and Access Management (IAM) service role to
communicate with AWS Systems Manager. Systems Manager assumes this role to enable Systems
Manager capabilities on each core device. The Systems Manager Agent component also uses this role
to register the core device as a Systems Manager managed node when you deploy the component. If
you haven't already done so, create a Systems Manager service role for the Systems Manager Agent
component to use. For more information, see Create an IAM service role for edge devices in the AWS
Systems Manager User Guide.
Step 3: Add permissions to the token exchange role
Greengrass core devices use an IAM service role, called the token exchange role, to interact with AWS
services. Each core device has a token exchange role that you create when you install the AWS IoT
Greengrass Core software (p. 67). Many Greengrass components, such as the Systems Manager Agent,
require additional permissions on this role. The Systems Manager agent component requires the
following permissions, which include permission to use the role that you created in Step 2: Create an IAM
service role for Systems Manager (p. 762).
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"iam:PassRole"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iam::account-id:role/SSMServiceRole"
]
},
{
"Action": [
"ssm:AddTagsToResource",
"ssm:RegisterManagedInstance"
],
"Effect": "Allow",
"Resource": "*"
}
762
AWS IoT Greengrass Developer Guide, Version 2
Step 3: Add permissions to the token exchange role
]
}
If you haven't already done so, add these permissions to the core device's token exchange role to allow
the Systems Manager Agent to operate. You can add a new policy to the token exchange role to grant
this permission.
To add permissions to the token exchange role (console)
1. In the IAM console navigation menu, choose Roles.
2. Choose the IAM role that you set up as a token exchange role when you installed the
AWS IoT Greengrass Core software. If you didn't specify a name for the token exchange
role when you installed the AWS IoT Greengrass Core software, it created a role named
GreengrassV2TokenExchangeRole.
3. Choose Attach policies.
4. Choose Create policy. The Create policy page opens in a new browser tab.
5. On the Create policy page, do the following:
a. Choose JSON to open the JSON editor.
b. Paste the following policy into the JSON editor. Replace SSMServiceRole with the name
of the service role that you created in Step 2: Create an IAM service role for Systems
Manager (p. 762).
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"iam:PassRole"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iam::account-id:role/SSMServiceRole"
]
},
{
"Action": [
"ssm:AddTagsToResource",
"ssm:RegisterManagedInstance"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
c. Choose Next: Tags.
d. Choose Next: Review.
e. Enter a Name for the policy, such as GreengrassSSMAgentComponentPolicy.
f. Choose Create policy.
g. Switch to the previous browser tab where you have the token exchange role open.
6. On the Add permissions to role page, choose the refresh button, and then select the Greengrass
Systems Manager agent policy that you created in the previous step.
7. Choose Attach policy.
The core devices that use this token exchange role now have permission to interact with the Systems
Manager service.
763
AWS IoT Greengrass Developer Guide, Version 2
Step 3: Add permissions to the token exchange role
To add permissions to the token exchange role (AWS CLI)
To add a policy that grants permission to use Systems Manager
1. Create a file called ssm-agent-component-policy.json and copy the following JSON into the
file. Replace SSMServiceRole with the name of the service role that you created in Step 2: Create
an IAM service role for Systems Manager (p. 762).
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"iam:PassRole"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iam::account-id:role/SSMServiceRole"
]
},
{
"Action": [
"ssm:AddTagsToResource",
"ssm:RegisterManagedInstance"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
2. Run the following command to create the policy from the policy document in ssm-agent-
component-policy.json.
Linux or Unix
aws iam create-policy \
--policy-name GreengrassSSMAgentComponentPolicy \
--policy-document file://ssm-agent-component-policy.json
Windows Command Prompt (CMD)
aws iam create-policy ^
--policy-name GreengrassSSMAgentComponentPolicy ^
--policy-document file://ssm-agent-component-policy.json
PowerShell
aws iam create-policy `
--policy-name GreengrassSSMAgentComponentPolicy `
--policy-document file://ssm-agent-component-policy.json
Copy the policy Amazon Resource Name (ARN) from the policy metadata in the output. You use this
ARN to attach this policy to the core device role in the next step.
3. Run the following command to attach the policy to the token exchange role.
• Replace GreengrassV2TokenExchangeRole with the name of the token exchange role that you
specified when you installed the AWS IoT Greengrass Core software. If you didn't specify a name
764
AWS IoT Greengrass Developer Guide, Version 2
Step 4: Deploy the Systems Manager Agent component
for the token exchange role when you installed the AWS IoT Greengrass Core software, it created a
role named GreengrassV2TokenExchangeRole.
• Replace the policy ARN with the ARN from the previous step.
Linux or Unix
aws iam attach-role-policy \
--role-name GreengrassV2TokenExchangeRole \
--policy-arn arn:aws:iam::123456789012:policy/GreengrassSSMAgentComponentPolicy
Windows Command Prompt (CMD)
aws iam attach-role-policy ^
--role-name GreengrassV2TokenExchangeRole ^
--policy-arn arn:aws:iam::123456789012:policy/GreengrassSSMAgentComponentPolicy
PowerShell
aws iam attach-role-policy `
--role-name GreengrassV2TokenExchangeRole `
--policy-arn arn:aws:iam::123456789012:policy/GreengrassSSMAgentComponentPolicy
If the command has no output, it succeeded. The core devices that use this token exchange role now
have permission to interact with the Systems Manager service.
Step 4: Deploy the Systems Manager Agent
component
Complete the following steps to deploy and configure the Systems Manager Agent component. You can
deploy the component to a single core device or to a group of core devices.
To deploy the Systems Manager Agent component (console)
1. In the AWS IoT Greengrass console navigation menu, choose Components.
2. On the Components page, choose the Public components tab, and then choose
aws.greengrass.SystemsManagerAgent.
3. On the aws.greengrass.SystemsManagerAgent page, choose Deploy.
4. From Add to deployment, choose an existing deployment to revise, or choose to create a new
deployment, and then choose Next.
5. If you chose to create a new deployment, choose the target core device or thing group for the
deployment. On the Specify target page, under Deployment target, choose a core device or thing
group, and then choose Next.
6. On the Select components page, under Public components, select
aws.greengrass.SystemsManagerAgent, and then choose Next.
7. On the Configure components page, select aws.greengrass.SystemsManagerAgent, and then do
the following:
a. Choose Configure component.
b. In the Configure aws.greengrass.SystemsManagerAgent modal, under Configuration
update, in Configuration to merge, enter the following configuration update. Replace
765
AWS IoT Greengrass Developer Guide, Version 2
Step 4: Deploy the Systems Manager Agent component
SSMServiceRole with the name of the service role that you created in Step 2: Create an IAM
service role for Systems Manager (p. 762).
{
"SSMRegistrationRole": "SSMServiceRole",
"SSMOverrideRegistration": false
}
Note
If the core device already runs the SSM agent software without the SSM agent
component, change SSMOverrideRegistration to true. This parameter specifies
whether the SSM agent component registers the core device when the SSM agent is
already running on the device.
You can also specify tags (SSMResourceTags) to add to the Systems Manager
managed node that the SSM agent component creates for the core device. For more
information, see SSM agent component configuration (p. 406).
c. Choose Confirm to close the modal, and then choose Next.
8. On the Configure advanced settings page, keep the default configuration settings, and choose
Next.
9. On the Review page, choose Deploy
To deploy the Systems Manager Agent component (AWS CLI)
To deploy the Systems Manager Agent component, create a deployment document that includes
aws.greengrass.SystemsManagerAgent in the components object, and specify the configuration
update for the component. Follow instructions in Create deployments (p. 493) to create a new
deployment or revise an existing deployment.
The following example partial deployment document specifies to use a service role named
SSMServiceRole. Replace SSMServiceRole with the name of the service role that you created in Step
2: Create an IAM service role for Systems Manager (p. 762).
{
...,
"components": {
...,
"aws.greengrass.SystemsManagerAgent": {
"componentVersion": "1.0.0",
"configurationUpdate": {
"merge": "{\"SSMRegistrationRole\":\"SSMServiceRole\",\"SSMOverrideRegistration
\":false}"
}
}
}
}
Note
If the core device already runs the SSM agent software without the SSM agent component,
change SSMOverrideRegistration to true. This parameter specifies whether the SSM agent
component registers the core device when the SSM agent is already running on the device.
You can also specify tags (SSMResourceTags) to add to the Systems Manager managed node
that the SSM agent component creates for the core device. For more information, see SSM agent
component configuration (p. 406).
The deployment can take several minutes to complete. You can use the AWS IoT Greengrass service to
check the status of the deployment, and you can check the AWS IoT Greengrass Core software logs and
766
AWS IoT Greengrass Developer Guide, Version 2
Step 5: Verify core device
registration with Systems Manager
Systems Manager Agent component logs to verify that the Systems Manager Agent runs successfully. For
more information, see the following:
• Check deployment status (p. 504)
• Monitor AWS IoT Greengrass logs (p. 506)
• Viewing Systems Manager Agent logs in the AWS Systems Manager User Guide
If the deployment fails or the Systems Manager Agent doesn't run, you can troubleshoot the deployment
on each core device. For more information, see the following:
• Troubleshooting AWS IoT Greengrass V2 (p. 911)
• Troubleshooting Systems Manager Agent in the AWS Systems Manager User Guide
Step 5: Verify core device registration with Systems
Manager
When the Systems Manager Agent component runs, it registers the core device as a managed node in
Systems Manager. You can use the AWS IoT Greengrass console, Systems Manager console, and Systems
Manager API to verify that a core device is registered as a managed node. Managed nodes are also called
instances in parts of the AWS console and API.
To verify core device registration (AWS IoT Greengrass console)
1. In the AWS IoT Greengrass console navigation menu, choose Core devices.
2. Choose the core device to verify.
3. On the core device's details page, find the AWS Systems Manager instance property. If this property
is present and displays a link to the Systems Manager console, the core device is registered as a
managed node.
You can also find the AWS Systems Manager ping status property to check the status of the
Systems Manager Agent on the core device. When the status is Online, you can manage the core
device with Systems Manager.
To verify core device registration (Systems Manager console)
1. In the Systems Manager console navigation menu, choose Fleet Manager.
2. Under Managed nodes, do the following:
a. Add a filter where Source type is AWS::IoT::Thing.
b. Add a filter where Source ID is the name of the core device to verify.
3. Find the core device in the Managed nodes table. If the core device is in the table, it's registered as a
managed node.
You can also find the Systems Manager Agent ping status property to check the status of the
Systems Manager Agent on the core device. When the status is Online, you can manage the core
device with Systems Manager.
767
AWS IoT Greengrass Developer Guide, Version 2
Uninstall the Systems Manager Agent
To verify core device registration (AWS CLI)
• Use the DescribeInstanceInformation operation to get the list of managed nodes that match a
filter that you specify. Run the following command to verify whether a core device is registered as a
managed node. Replace MyGreengrassCore with the name of the core device to verify.
aws ssm describe-instance-information --filter Key=SourceIds,Values=MyGreengrassCore
Key=SourceTypes,Values=AWS::IoT::Thing
The response contains the list of managed nodes that match the filter. If the list contains a managed
node, the core device is registered as a managed node. You can also find other information about
the core device's managed node in the response. If the PingStatus property is Online, you can
manage the core device with Systems Manager.
After you verify that a core device is registered as a managed node in Systems Manager, you can use
the Systems Manager console and API to manage that core device. For more information about the
Systems Manager capabilities that you can use to manage Greengrass core devices, see Systems Manager
capabilities in the AWS Systems Manager User Guide.
Uninstall the AWS Systems Manager Agent
If you no longer want to manage a Greengrass core device with AWS Systems Manager, you can
deregister the core device from Systems Manager and uninstall the AWS Systems Manager Agent
(Systems Manager Agent) from the device.
You can reregister a core device again at any time. To do so, deploy the Systems Manager Agent
component again, which registers the core device with Systems Manager when it installs. Systems
Manager stores the command history for a deregistered core device for 30 days.
Topics
• Step 1: Deregister the core device from Systems Manager (p. 768)
• Step 2: Uninstall the Systems Manager Agent component (p. 768)
• Step 3: Uninstall the Systems Manager Agent software (p. 769)
Step 1: Deregister the core device from Systems
Manager
You can use the Systems Manager console or API to deregister the core device. For more information, see
Deregistering managed nodes in the AWS Systems Manager User Guide.
Step 2: Uninstall the Systems Manager Agent
component
After you deregister the core device, uninstall the Systems Manager Agent component (p. 403) from the
device. To remove a component from a Greengrass core device, revise the deployment that installed the
component, and remove the component from the deployment. The AWS IoT Greengrass Core software
uninstalls a component when none of a core device's deployments specify that component. For more
information, see Deploy AWS IoT Greengrass components to devices (p. 491).
768
AWS IoT Greengrass Developer Guide, Version 2
Step 3: Uninstall the Systems Manager Agent software
To uninstall the Systems Manager Agent component (console)
1. In the AWS IoT Greengrass console navigation menu, choose Core devices.
2. Choose the core device where you want to uninstall the Systems Manager Agent component.
3. On the core device details page, choose the Deployments tab.
4. Choose the deployment that deploys the Systems Manager Agent component to the core device.
5. On the deployment details page, choose Revise.
6. In the Revise deployment modal, choose Revise deployment.
7. In Step 1: Specify target, choose Next.
8. In Step 2: Select components, clear the selection for the aws.greengrass.SystemsManagerAgent
component, and then choose Next.
9. In Step 3: Configure components, choose Next.
10. In Step 4: Configure advanced settings, choose Next.
11. In Step 5: Review, choose Deploy.
To uninstall the Systems Manager Agent component (CLI)
To uninstall the Systems Manager Agent component, revise the deployment that deploys it, and remove
it from the deployment. For more information, see Revise deployments (p. 502).
The deployment can take several minutes to complete. You can use the AWS IoT Greengrass service to
check the status of the deployment. For more information, see Check deployment status (p. 504).
Step 3: Uninstall the Systems Manager Agent
software
The Systems Manager Agent software continues to run on the core device after you remove the Systems
Manager Agent component. To remove the Systems Manager Agent software, you can run commands on
the core device. For more information, see Uninstall Systems Manager Agent from Linux instances in the
AWS Systems Manager User Guide.
769
AWS IoT Greengrass Developer Guide, Version 2
Data protection
Security in AWS IoT Greengrass
Cloud security at AWS is the highest priority. As an AWS customer, you benefit from a data center and
network architecture that is built to meet the requirements of the most security-sensitive organizations.
Security is a shared responsibility between AWS and you. The shared responsibility model describes this
as security of the cloud and security in the cloud:
• Security of the cloud – AWS is responsible for protecting the infrastructure that runs AWS services in
the AWS Cloud. AWS also provides you with services that you can use securely. Third-party auditors
regularly test and verify the effectiveness of our security as part of the AWS Compliance Programs. To
learn about the compliance programs that apply to AWS IoT Greengrass, see AWS Services in Scope by
Compliance Program.
• Security in the cloud – Your responsibility is determined by the AWS service that you use. You are also
responsible for other factors, including the sensitivity of your data, your company's requirements, and
applicable laws and regulations.
When you use AWS IoT Greengrass, you are also responsible for securing your devices, local network
connection, and private keys.
This documentation helps you understand how to apply the shared responsibility model when using
AWS IoT Greengrass. The following topics show you how to configure AWS IoT Greengrass to meet
your security and compliance objectives. You also learn how to use other AWS services that help you to
monitor and secure your AWS IoT Greengrass resources.
Topics
• Data protection in AWS IoT Greengrass (p. 770)
• Device authentication and authorization for AWS IoT Greengrass (p. 773)
• Identity and access management for AWS IoT Greengrass (p. 781)
• Allow device traffic through a proxy or firewall (p. 807)
• Compliance validation for AWS IoT Greengrass (p. 810)
• Resilience in AWS IoT Greengrass (p. 811)
• Infrastructure security in AWS IoT Greengrass (p. 811)
• Configuration and vulnerability analysis in AWS IoT Greengrass (p. 812)
• Code integrity in AWS IoT Greengrass V2 (p. 812)
• AWS IoT Greengrass and interface VPC endpoints (AWS PrivateLink) (p. 813)
• Security best practices for AWS IoT Greengrass (p. 815)
Data protection in AWS IoT Greengrass
The AWS shared responsibility model applies to data protection in AWS IoT Greengrass. As described in
this model, AWS is responsible for protecting the global infrastructure that runs all of the AWS Cloud.
You are responsible for maintaining control over your content that is hosted on this infrastructure. This
content includes the security configuration and management tasks for the AWS services that you use. For
770
AWS IoT Greengrass Developer Guide, Version 2
Data encryption
more information about data privacy, see the Data Privacy FAQ. For information about data protection in
Europe, see the AWS Shared Responsibility Model and GDPR blog post on the AWS Security Blog.
For data protection purposes, we recommend that you protect AWS account credentials and set up
individual user accounts with AWS Identity and Access Management (IAM). That way each user is given
only the permissions necessary to fulfill their job duties. We also recommend that you secure your data
in the following ways:
• Use multi-factor authentication (MFA) with each account.
• Use SSL/TLS to communicate with AWS resources. We recommend TLS 1.2 or later.
• Set up API and user activity logging with AWS CloudTrail.
• Use AWS encryption solutions, along with all default security controls within AWS services.
• Use advanced managed security services such as Amazon Macie, which assists in discovering and
securing personal data that is stored in Amazon S3.
• If you require FIPS 140-2 validated cryptographic modules when accessing AWS through a command
line interface or an API, use a FIPS endpoint. For more information about the available FIPS endpoints,
see Federal Information Processing Standard (FIPS) 140-2.
We strongly recommend that you never put confidential or sensitive information, such as your
customers' email addresses, into tags or free-form fields such as a Name field. This includes when
you work with AWS IoT Greengrass or other AWS services using the console, API, AWS CLI, or AWS
SDKs. Any data that you enter into tags or free-form fields used for names may be used for billing or
diagnostic logs. If you provide a URL to an external server, we strongly recommend that you do not
include credentials information in the URL to validate your request to that server.
For more information about protecting sensitive information in AWS IoT Greengrass, see the section
called “Don't log sensitive information” (p. 815).
For more information about data protection, see the AWS Shared Responsibility Model and GDPR blog
post on the AWS Security Blog.
Topics
• Data encryption (p. 771)
Data encryption
AWS IoT Greengrass uses encryption to protect data while in-transit (over the internet or local network)
and at rest (stored in the AWS Cloud).
Devices in a AWS IoT Greengrass environment often collect data that's sent to AWS services for further
processing. For more information about data encryption on other AWS services, see the security
documentation for that service.
Topics
• Encryption in transit (p. 771)
• Encryption at rest (p. 772)
• Key management for the Greengrass core device (p. 772)
Encryption in transit
AWS IoT Greengrass has two modes of communication where data is in transit:
771
AWS IoT Greengrass Developer Guide, Version 2
Data encryption
• the section called “Data in transit over the internet” (p. 772). Communication between a Greengrass
core and AWS IoT Greengrass over the internet is encrypted.
• the section called “Data on the core device” (p. 772). Communication between components on the
Greengrass core device is not encrypted.
Data in transit over the internet
AWS IoT Greengrass uses Transport Layer Security (TLS) to encrypt all communication over the internet.
All data sent to the AWS Cloud is sent over a TLS connection using MQTT or HTTPS protocols, so it is
secure by default. AWS IoT Greengrass uses the AWS IoT transport security model. For more information,
see Transport security in the AWS IoT Core Developer Guide.
Data on the core device
AWS IoT Greengrass doesn't encrypt data exchanged locally on the Greengrass core device because the
data doesn't leave the device. This includes communication between user-defined components, the AWS
IoT device SDK, and public components, such as stream manager.
Encryption at rest
AWS IoT Greengrass stores your data:
• the section called “Data at rest in the AWS Cloud” (p. 772). This data is encrypted.
• the section called “Data at rest on the Greengrass core” (p. 772). This data is not encrypted (except
local copies of your secrets).
Data at rest in the AWS Cloud
AWS IoT Greengrass encrypts customer data stored in the AWS Cloud. This data is protected using AWS
KMS keys that are managed by AWS IoT Greengrass.
Data at rest on the Greengrass core
AWS IoT Greengrass relies on Unix file permissions and full-disk encryption (if enabled) to protect data at
rest on the core. It is your responsibility to secure the file system and device.
However, AWS IoT Greengrass does encrypt local copies of your secrets retrieved from AWS Secrets
Manager. For more information, see the secret manager (p. 374) component.
Key management for the Greengrass core device
It's the responsibility of the customer to guarantee secure storage of cryptographic (public and private)
keys on the Greengrass core device. AWS IoT Greengrass uses public and private keys for the following
scenario:
• The IoT client key is used with the IoT certificate to authenticate the Transport Layer Security (TLS)
handshake when a Greengrass core connects to AWS IoT Core. For more information, see the section
called “Device authentication and authorization” (p. 773).
Note
The key and certificate are also referred to as the core private key and the core device
certificate.
A Greengrass core supports private key storage using file system permissions. If you use file system-
based private keys, you are responsible for their secure storage on the core device.
772
AWS IoT Greengrass Developer Guide, Version 2
Device authentication and authorization
Device authentication and authorization for AWS
IoT Greengrass
Devices in AWS IoT Greengrass environments use X.509 certificates for authentication and AWS IoT
policies for authorization. Certificates and policies allow devices to securely connect with each other,
AWS IoT Core, and AWS IoT Greengrass.
X.509 certificates are digital certificates that use the X.509 public key infrastructure standard to
associate a public key with the identity contained in a certificate. X.509 certificates are issued by a
trusted entity called a certificate authority (CA). The CA maintains one or more special certificates called
CA certificates that it uses to issue X.509 certificates. Only the certificate authority has access to CA
certificates.
AWS IoT policies define the set of operations allowed for AWS IoT devices. Specifically, they allow and
deny access to AWS IoT Core and AWS IoT Greengrass data plane operations, such as publishing MQTT
messages and retrieving device shadows.
All devices require an entry in the AWS IoT Core registry and an activated X.509 certificate with an
attached AWS IoT policy. Devices fall into two categories:
• Greengrass core devices
Greengrass core devices use certificates and AWS IoT policies to connect to AWS IoT Core and AWS IoT
Greengrass. The certificates and policies also allow AWS IoT Greengrass to deploy components and
configurations to core devices.
• Client devices
MQTT client devices use certificates and policies to connect to AWS IoT Core and the AWS IoT
Greengrass service. This enables client devices to use the AWS IoT Greengrass cloud discovery to find
and connect to a Greengrass core device. A client device uses the same certificate to connect to the
AWS IoT Core cloud service and core devices. Client devices also use discovery information for mutual
authentication with the core device. For more information, see Interact with local IoT devices (p. 638).
X.509 certificates
Communication between core devices and client devices and between devices and AWS IoT Core or AWS
IoT Greengrass must be authenticated. This mutual authentication is based on registered X.509 device
certificates and cryptographic keys.
In an AWS IoT Greengrass environment, devices use certificates with public and private keys for the
following Transport Layer Security (TLS) connections:
• The AWS IoT client component on the Greengrass core device that connects to AWS IoT Core and AWS
IoT Greengrass over the internet.
• Client devices that connect to AWS IoT Greengrass over the internet to discover core devices.
• The MQTT broker component on the Greengrass core connecting to Greengrass devices in the group
over the local network.
AWS IoT Greengrass core devices store certificates in the Greengrass root folder.
Certificate authority (CA) certificates
Greengrass core devices and client devices download a root CA certificate used for authentication with
the AWS IoT Core and AWS IoT Greengrass services. We recommend that you use an Amazon Trust
773
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT policies
Services (ATS) root CA certificate, such as Amazon Root CA 1. For more information, see CA certificates
for server authentication in the AWS IoT Core Developer Guide.
Client devices also download a Greengrass core device CA certificate. They use this certificate to validate
the MQTT server certificate on the core device during mutual authentication.
Certificate rotation on the local MQTT broker
Greengrass core devices generate a local MQTT server certificate that client devices use for mutual
authentication. This certificate is signed by the core device CA certificate, which the core device stores in
the AWS IoT Greengrass cloud. Client devices retrieve the core device CA certificate when they discover
the core device. They use the core device CA certificate to verify the core device's MQTT server certificate
when they connect to the core device. The core device CA certificate expires after 5 years.
The MQTT server certificate expires every 7 days. This limited period is based on security best practices.
This rotation helps mitigate the threat of an attacker stealing the MQTT server certificate and private key
to impersonate the Greengrass core device.
When the MQTT server certificate expires, the Greengrass core device generates a new certificate and
restarts the local MQTT broker. When this happens, all client devices connected to the Greengrass core
device are disconnected. Client devices can reconnect to the Greengrass core device after a short period
of time.
AWS IoT policies for data plane operations
Use AWS IoT policies to authorize access to the AWS IoT Core and AWS IoT Greengrass data planes.
The AWS IoT Core data plane provides operations for devices, users, and applications. These operations
include the ability to connect to AWS IoT Core and subscribe to topics. The AWS IoT Greengrass data
plane provides operations for Greengrass devices. These operations include the ability to resolve
component dependencies and download public component artifacts.
An AWS IoT policy is a JSON document that's similar to an IAM policy. It contains one or more policy
statements that specify the following properties:
• Effect. The access mode, which can be Allow or Deny.
• Action. The list of actions that are allowed or denied by the policy.
• Resource. The list of resources on which the action is allowed or denied.
AWS IoT policies support * as a wildcard character, and treat MQTT wildcard characters (+ and #) as
literal strings. For more information about the * wildcard, see Using wildcard in resource ARNs in the
AWS Identity and Access Management User Guide.
For more information, see AWS IoT policies and AWS IoT policy actions in the AWS IoT Core Developer
Guide.
Important
Thing policy variables (iot:Connection.Thing.*) aren't supported for in AWS IoT policies for
core devices or Greengrass data plane operations. Instead, you can use a wildcard that matches
multiple devices that have similar names. For example, you can specify MyGreengrassDevice*
to match MyGreengrassDevice1, MyGreengrassDevice2, and so on.
Note
AWS IoT Core enables you to attach AWS IoT policies to thing groups to define permissions for
groups of devices. Thing group policies don't allow access to AWS IoT Greengrass data plane
operations. To allow a thing access to an AWS IoT Greengrass data plane operation, add the
permission to an AWS IoT policy that you attach to the thing's certificate.
774
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT policies
AWS IoT Greengrass V2 policy actions
AWS IoT Greengrass V2 defines the following policy actions that Greengrass core devices and client
devices can use in AWS IoT policies:
Core device actions
greengrass:GetComponentVersionArtifact
Grants permission to get a presigned URL to download a public component artifact.
This permission is evaluated when a core device receives a deployment that specifies a public
component that has artifacts. If the core device already has the artifact, it doesn't download the
artifact again.
greengrass:ResolveComponentCandidates
Grants permission to identify a list of components that meet the component, version, and platform
requirements for a deployment. If the requirements conflict, or no components exist that meet the
requirements, this operation returns an error and the deployment fails on the device.
This permission is evaluated when a core device receives a deployment that specifies components.
greengrass:GetDeploymentConfiguration
Grants permission to get a presigned URL to download a large deployment document.
This permission is evaluated when a core device receives a deployment that specifies a deployment
document larger than 7 KB (if the deployment targets a thing) or 31 KB (if the deployment targets a
thing group). The deployment document includes component configurations, deployment policies,
and deployment metadata. For more information, see Deploy AWS IoT Greengrass components to
devices (p. 491).
This feature is available for v2.3.0 and later of the Greengrass nucleus component (p. 181).
greengrass:ListThingGroupsForCoreDevice
Grants permission to get a core device's thing group hierarchy.
This permission is checked when a core device receives a deployment from AWS IoT Greengrass. The
core device uses this action to identify whether it was removed from a thing group since the last
deployment. If the core device was removed from a thing group, and that thing group is the target
of a deployment to the core device, then the core device removes the components installed by that
deployment.
This feature is used by v2.5.0 and later of the Greengrass nucleus component (p. 181).
greengrass:VerifyClientDeviceIdentity
Grants permission to verify the identity of a client device that connects to a core device.
This permission is evaluated when a core device receives an MQTT connection from a client device.
The client device presents its AWS IoT device certificate. Then, the core device sends the device
certificate to the AWS IoT Greengrass cloud service to verify the client device's identity. For more
information, see Interact with local IoT devices (p. 638).
greengrass:VerifyClientDeviceIoTCertificateAssociation
Grants permission to verify whether a client device is associated with an AWS IoT certificate.
This permission is evaluated when a core device authorizes a client device to connect over MQTT. For
more information, see Interact with local IoT devices (p. 638).
775
AWS IoT Greengrass Developer Guide, Version 2
Update a core device's AWS IoT policy
Note
For a core device to use this operation, the Greengrass service role (p. 796) must be
associated to your AWS account and allow the iot:DescribeCertificate permission.
greengrass:PutCertificateAuthorities
Grants permission to upload certificate authority (CA) certificates that client devices can download
to verify the core device.
This permission is evaluated when a core device installs and runs the client device auth
component (p. 194). This component creates a local certificate authority and uses this operation
to upload its CA certificates. Client devices download these CA certificates when they use the
Discover (p. 776) operation to find core devices where they can connect. When client devices
connect to an MQTT broker on a core device, they use these CA certificates to verify the identity of
the core device. For more information, see Interact with local IoT devices (p. 638).
greengrass:GetConnectivityInfo
Grants permission to get connectivity information for a core device. This information describes how
client devices can connect to the core device.
This permission is evaluated when a core device installs and runs the client device auth
component (p. 194). This component uses the connectivity information to generate
valid CA certificates to upload to the AWS IoT Greengrass cloud service with the
PutCertificateAuthories (p. 776) operation. Client devices use these CA certificates to verify the
identity of the core device. For more information, see Interact with local IoT devices (p. 638).
You can also use this operation on the AWS IoT Greengrass control plane to view connectivity
information for a core device. For more information, see GetConnectivityInfo in the AWS IoT
Greengrass V1 API Reference.
greengrass:UpdateConnectivityInfo
Grants permission to update connectivity information for a core device. This information describes
how client devices can connect to the core device.
This permission is evaluated when a core device runs the IP detector component (p. 240). This
component identifies the information that client devices require to connect to the core device on
the local network. Then, this component uses this operation to upload the connectivity information
to the AWS IoT Greengrass cloud service, so client devices can retrieve this information with the
Discover (p. 776) operation. For more information, see Interact with local IoT devices (p. 638).
You can also use this operation on the AWS IoT Greengrass control plane to manually update
connectivity information for a core device. For more information, see UpdateConnectivityInfo in the
AWS IoT Greengrass V1 API Reference.
Client device actions
greengrass:Discover
Grants permission to discover connectivity information for core devices where a client device
can connect. This information describes how the client device can connect to the core devices.
A client device can discover only the core devices that you have associated it with by using the
BatchAssociateClientDeviceWithCoreDevice operation. For more information, see Interact with local
IoT devices (p. 638).
Update a core device's AWS IoT policy
You can use the AWS IoT Greengrass and AWS IoT consoles to view and update a core device's AWS IoT
policy.
776
AWS IoT Greengrass Developer Guide, Version 2
Minimal AWS IoT policy
Note
If you used the AWS IoT Greengrass Core software installer to provision resources (p. 69),
your core device has an AWS IoT policy that allows access to all AWS IoT Greengrass actions
(greengrass:*). You can follow these steps to restrict access to only the actions that a core
device uses.
To review and update a core device's AWS IoT policy
1. In the AWS IoT Greengrass console navigation menu, choose Core devices.
2. On the Core devices page, choose the core device to update.
3. On the core device details page, choose the link to the core device's Thing. This link opens the thing
details page in the AWS IoT console.
4. On the thing details page, choose Certificates.
5. In the Certificates tab, choose the thing's active certificate.
6. On the certificate details page, choose Policies.
7. In the Policies tab, choose the AWS IoT policy to review and update. You can add the required
permissions to any policy that is attached to the core device's active certificate.
Note
If you used the AWS IoT Greengrass Core software installer to provision resources (p. 69),
you have two AWS IoT policies. We recommend that you choose the policy named
GreengrassV2IoTThingPolicy, if it exists. Core devices that you create with the quick
installer use this policy name by default. If you add permissions to this policy, you are also
granting these permissions to other core devices that use this policy.
8. In the policy overview, choose Edit policy document.
9. Review the policy and add, remove, or edit permissions as needed.
10. Choose Save as new version.
Minimal AWS IoT policy for AWS IoT Greengrass V2
core devices
Important
Later versions of the Greengrass nucleus component (p. 181) require additional permissions
on the minimal AWS IoT policy. You might need to update your core devices' AWS IoT
policies (p. 776) to grant additional permissions.
• Core devices that run Greengrass nucleus v2.5.0 and later require the
greengrass:ListThingGroupsForCoreDevice permission.
• Core devices that run Greengrass nucleus v2.3.0 and later require the
greengrass:GetDeploymentConfiguration permission to support large deployment
configuration documents.
The following example policy includes the minimum set of actions required to support basic Greengrass
functionality for your core device.
• The policy includes the * wildcard after the core device thing name (For example, core-device-
thing-name*). The core device uses the same device certificate to make multiple connections to AWS
IoT Core, but the client ID in a connection might not be an exact match of the core device thing name.
This wildcard allows the core device to connect when it uses a client ID with a suffix.
• The policy lists the MQTT topics and topic filters that the core device can publish messages to,
subscribe to, and receive messages on, including topics used for shadow state. To support message
exchange between AWS IoT Core, Greengrass components, and client devices, specify the topics and
777
AWS IoT Greengrass Developer Guide, Version 2
Minimal AWS IoT policy
topic filters that you want to allow. For more information, see Publish/Subscribe policy examples in
the AWS IoT Core Developer Guide.
• The policy grants permission to publish to the following topic for telemetry data.
$aws/things/core-device-thing-name*/greengrass/health/json
You can remove this permission for core devices where you disable telemetry. For more information,
see Gather system health telemetry data from AWS IoT Greengrass core devices (p. 515).
• The policy grants permission to assume an IAM role through an AWS IoT role alias. The core
device uses this role, called the token exchange role, to acquire AWS credentials that it can use to
authenticate AWS requests. For more information, see Authorize core devices to interact with AWS
services (p. 790).
When you install the AWS IoT Greengrass Core software, you create and attach a second AWS IoT
policy that includes only this permission. If you include this permission in your core device's primary
AWS IoT policy, you can detach and delete the other AWS IoT policy.
• The policy includes a section that allows AWS IoT Core to get, update, and delete the core
device's shadow. To allow shadow sync for connected devices in the Greengrass group,
specify the target Amazon Resource Names (ARNs) in the Resource list (for example,
arn:aws:iot:region:account-id:thing/device-name).
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Connect"
],
"Resource": "arn:aws:iot:region:account-id:client/core-device-thing-name*"
},
{
"Effect": "Allow",
"Action": [
"iot:Receive",
"iot:Publish"
],
"Resource": [
"arn:aws:iot:region:account-id:topic/$aws/things/core-device-thing-name*/
greengrass/health/json",
"arn:aws:iot:region:account-id:topic/$aws/things/core-device-thing-name*/
greengrassv2/health/json",
"arn:aws:iot:region:account-id:topic/$aws/things/core-device-thing-name*/
jobs/*",
"arn:aws:iot:region:account-id:topic/$aws/things/core-device-thing-name*/
shadow/*"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:region:account-id:topicfilter/$aws/things/core-device-thing-
name*/jobs/*",
"arn:aws:iot:region:account-id:topicfilter/$aws/things/core-device-thing-
name*/shadow/*"
]
},
778
AWS IoT Greengrass Developer Guide, Version 2
Minimal AWS IoT policy to support client devices
{
"Effect": "Allow",
"Action": [
"iot:GetThingShadow",
"iot:UpdateThingShadow",
"iot:DeleteThingShadow"
],
"Resource": [
"arn:aws:iot:region:account-id:thing/core-device-thing-name*"
]
},
{
"Effect": "Allow",
"Action": "iot:AssumeRoleWithCertificate",
"Resource": "arn:aws:iot:region:account-id:rolealias/token-exchange-role-alias-
name"
},
{
"Effect": "Allow",
"Action": [
"greengrass:GetComponentVersionArtifact",
"greengrass:ResolveComponentCandidates",
"greengrass:GetDeploymentConfiguration",
"greengrass:ListThingGroupsForCoreDevice"
],
"Resource": "*"
}
]
}
Minimal AWS IoT policy to support client devices
The following example policy includes the minimum set of actions required to support interaction with
client devices on a core device. To support client devices, a core device must have the permissions in this
AWS IoT policy in addition to the Minimal AWS IoT policy for basic operation (p. 777).
• The policy allows the core device to get, update, and delete the shadow for any AWS IoT thing.
These permissions allow the core device to manage and sync shadows for client devices. To follow
best security practices, restrict the iot:GetThingShadow, iot:UpdateThingShadow, and
iot:DeleteThingShadow operations to the minimal set of client devices that connect to the core
device for your use case.
• The policy allows the core device to update its own connectivity information. This permission is
required only if you deploy the IP detector component (p. 240) to the core device.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"greengrass:PutCertificateAuthorities",
"greengrass:VerifyClientDeviceIdentity"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"greengrass:VerifyClientDeviceIoTCertificateAssociation"
],
"Resource": "arn:aws:iot:region:account-id:thing/*"
779
AWS IoT Greengrass Developer Guide, Version 2
Minimal AWS IoT policy for client devices
},
{
"Effect": "Allow",
"Action": [
"greengrass:GetConnectivityInfo",
"greengrass:UpdateConnectivityInfo"
],
"Resource": [
"arn:aws:greengrass:region:account-id:/greengrass/things/core-device-thing-
name*/connectivityInfo"
]
},
{
"Effect": "Allow",
"Action": [
"iot:GetThingShadow",
"iot:UpdateThingShadow",
"iot:DeleteThingShadow"
],
"Resource": [
"arn:aws:iot:region:account-id:thing/*"
]
}
]
}
Minimal AWS IoT policy for client devices
The following example policy includes the minimum set of actions required for a client device to discover
core devices where they connect and communicate over MQTT. The client device's AWS IoT policy must
include the greengrass:Discover action to allow the device to discover connectivity information for
its associated Greengrass core devices. In the Resource section, specify the Amazon Resource Name
(ARN) of the client device, not the ARN of the Greengrass core device.
• The policy allows communication on all MQTT topics. To follow best security practices, restrict the
iot:Publish, iot:Subscribe, and iot:Receive permissions to the minimal set of topics that a
client device requires for your use case.
• The policy allows the thing to discover core devices for all AWS IoT things. To follow best security
practices, restrict the greengrass:Discover permission to the client device's AWS IoT thing or a
wildcard that matches a set of AWS IoT things.
Important
Thing policy variables (iot:Connection.Thing.*) aren't supported for in AWS IoT
policies for core devices or Greengrass data plane operations. Instead, you can use a wildcard
that matches multiple devices that have similar names. For example, you can specify
MyGreengrassDevice* to match MyGreengrassDevice1, MyGreengrassDevice2, and
so on.
• A client device's AWS IoT policy doesn't typically require permissions for iot:GetThingShadow,
iot:UpdateThingShadow, or iot:DeleteThingShadow actions, because the Greengrass core
device handles shadow sync operations for client devices. To enable the core device to handle client
device shadows, check that the core device's AWS IoT policy allows these actions, and that the
Resource section includes the ARNs of the client devices.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
780
AWS IoT Greengrass Developer Guide, Version 2
Identity and access management
"iot:Connect"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:region:account-id:topic/*"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:region:account-id:topicfilter/*"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:region:account-id:topic/*"
]
},
{
"Effect": "Allow",
"Action": [
"greengrass:Discover"
],
"Resource": [
"arn:aws:iot:region:account-id:thing/*"
]
}
]
}
Identity and access management for AWS IoT
Greengrass
AWS Identity and Access Management (IAM) is an AWS service that helps an administrator securely
control access to AWS resources. IAM administrators control who can be authenticated (signed in) and
authorized (have permissions) to use AWS IoT Greengrass resources. IAM is an AWS service that you can
use with no additional charge.
Note
This topic describes IAM concepts and features. For information about IAM features supported
by AWS IoT Greengrass, see the section called “How AWS IoT Greengrass works with
IAM” (p. 785).
781
AWS IoT Greengrass Developer Guide, Version 2
Audience
Audience
How you use AWS Identity and Access Management (IAM) differs, depending on the work that you do in
AWS IoT Greengrass.
Service user – If you use the AWS IoT Greengrass service to do your job, then your administrator provides
you with the credentials and permissions that you need. As you use more AWS IoT Greengrass features
to do your work, you might need additional permissions. Understanding how access is managed can help
you request the right permissions from your administrator. If you cannot access a feature in AWS IoT
Greengrass, see Troubleshooting identity and access issues for AWS IoT Greengrass (p. 805).
Service administrator – If you're in charge of AWS IoT Greengrass resources at your company, you
probably have full access to AWS IoT Greengrass. It's your job to determine which AWS IoT Greengrass
features and resources your employees should access. You must then submit requests to your IAM
administrator to change the permissions of your service users. Review the information on this page to
understand the basic concepts of IAM. To learn more about how your company can use IAM with AWS IoT
Greengrass, see How AWS IoT Greengrass works with IAM (p. 785).
IAM administrator – If you're an IAM administrator, you might want to learn details about how you
can write policies to manage access to AWS IoT Greengrass. To view example AWS IoT Greengrass
identity-based policies that you can use in IAM, see Identity-based policy examples for AWS IoT
Greengrass (p. 789).
Authenticating with identities
Authentication is how you sign in to AWS using your identity credentials. For more information about
signing in using the AWS Management Console, see Signing in to the AWS Management Console as an
IAM user or root user in the IAM User Guide.
You must be authenticated (signed in to AWS) as the AWS account root user, an IAM user, or by assuming
an IAM role. You can also use your company's single sign-on authentication or even sign in using Google
or Facebook. In these cases, your administrator previously set up identity federation using IAM roles.
When you access AWS using credentials from another company, you are assuming a role indirectly.
To sign in directly to the AWS Management Console, use your password with your root user email
address or your IAM user name. You can access AWS programmatically using your root user or IAM
users access keys. AWS provides SDK and command line tools to cryptographically sign your request
using your credentials. If you don't use AWS tools, you must sign the request yourself. Do this using
Signature Version 4, a protocol for authenticating inbound API requests. For more information about
authenticating requests, see Signature Version 4 signing process in the AWS General Reference.
Regardless of the authentication method that you use, you might also be required to provide additional
security information. For example, AWS recommends that you use multi-factor authentication (MFA) to
increase the security of your account. To learn more, see Using multi-factor authentication (MFA) in AWS
in the IAM User Guide.
AWS account root user
When you first create an AWS account, you begin with a single sign-in identity that has complete access
to all AWS services and resources in the account. This identity is called the AWS account root user and
is accessed by signing in with the email address and password that you used to create the account. We
strongly recommend that you do not use the root user for your everyday tasks, even the administrative
ones. Instead, adhere to the best practice of using the root user only to create your first IAM user. Then
securely lock away the root user credentials and use them to perform only a few account and service
management tasks.
782
AWS IoT Greengrass Developer Guide, Version 2
Authenticating with identities
IAM users and groups
An IAM user is an identity within your AWS account that has specific permissions for a single person or
application. An IAM user can have long-term credentials such as a user name and password or a set of
access keys. To learn how to generate access keys, see Managing access keys for IAM users in the IAM
User Guide. When you generate access keys for an IAM user, make sure you view and securely save the key
pair. You cannot recover the secret access key in the future. Instead, you must generate a new access key
pair.
An IAM group is an identity that specifies a collection of IAM users. You can't sign in as a group. You
can use groups to specify permissions for multiple users at a time. Groups make permissions easier to
manage for large sets of users. For example, you could have a group named IAMAdmins and give that
group permissions to administer IAM resources.
Users are different from roles. A user is uniquely associated with one person or application, but a role
is intended to be assumable by anyone who needs it. Users have permanent long-term credentials, but
roles provide temporary credentials. To learn more, see When to create an IAM user (instead of a role) in
the IAM User Guide.
IAM roles
An IAM role is an identity within your AWS account that has specific permissions. It is similar to an IAM
user, but is not associated with a specific person. You can temporarily assume an IAM role in the AWS
Management Console by switching roles. You can assume a role by calling an AWS CLI or AWS API
operation or by using a custom URL. For more information about methods for using roles, see Using IAM
roles in the IAM User Guide.
IAM roles with temporary credentials are useful in the following situations:
• Temporary IAM user permissions – An IAM user can assume an IAM role to temporarily take on
different permissions for a specific task.
• Federated user access – Instead of creating an IAM user, you can use existing identities from AWS
Directory Service, your enterprise user directory, or a web identity provider. These are known as
federated users. AWS assigns a role to a federated user when access is requested through an identity
provider. For more information about federated users, see Federated users and roles in the IAM User
Guide.
• Cross-account access – You can use an IAM role to allow someone (a trusted principal) in a different
account to access resources in your account. Roles are the primary way to grant cross-account access.
However, with some AWS services, you can attach a policy directly to a resource (instead of using a role
as a proxy). To learn the difference between roles and resource-based policies for cross-account access,
see How IAM roles differ from resource-based policies in the IAM User Guide.
• Cross-service access – Some AWS services use features in other AWS services. For example, when you
make a call in a service, it's common for that service to run applications in Amazon EC2 or store objects
in Amazon S3. A service might do this using the calling principal's permissions, using a service role, or
using a service-linked role.
• Principal permissions – When you use an IAM user or role to perform actions in AWS, you are
considered a principal. Policies grant permissions to a principal. When you use some services, you
might perform an action that then triggers another action in a different service. In this case, you
must have permissions to perform both actions. To see whether an action requires additional
dependent actions in a policy, see Actions, Resources, and Condition Keys for AWS IoT Greengrass in
the Service Authorization Reference.
• Service role – A service role is an IAM role that a service assumes to perform actions on your behalf.
An IAM administrator can create, modify, and delete a service role from within IAM. For more
information, see Creating a role to delegate permissions to an AWS service in the IAM User Guide.
• Service-linked role – A service-linked role is a type of service role that is linked to an AWS service.
The service can assume the role to perform an action on your behalf. Service-linked roles appear
783
AWS IoT Greengrass Developer Guide, Version 2
Managing access using policies
in your IAM account and are owned by the service. An IAM administrator can view, but not edit the
permissions for service-linked roles.
• Applications running on Amazon EC2 – You can use an IAM role to manage temporary credentials
for applications that are running on an EC2 instance and making AWS CLI or AWS API requests.
This is preferable to storing access keys within the EC2 instance. To assign an AWS role to an EC2
instance and make it available to all of its applications, you create an instance profile that is attached
to the instance. An instance profile contains the role and enables programs that are running on the
EC2 instance to get temporary credentials. For more information, see Using an IAM role to grant
permissions to applications running on Amazon EC2 instances in the IAM User Guide.
To learn whether to use IAM roles or IAM users, see When to create an IAM role (instead of a user) in the
IAM User Guide.
Managing access using policies
You control access in AWS by creating policies and attaching them to IAM identities or AWS resources. A
policy is an object in AWS that, when associated with an identity or resource, defines their permissions.
You can sign in as the root user or an IAM user, or you can assume an IAM role. When you then make
a request, AWS evaluates the related identity-based or resource-based policies. Permissions in the
policies determine whether the request is allowed or denied. Most policies are stored in AWS as JSON
documents. For more information about the structure and contents of JSON policy documents, see
Overview of JSON policies in the IAM User Guide.
Administrators can use AWS JSON policies to specify who has access to what. That is, which principal can
perform actions on what resources, and under what conditions.
Every IAM entity (user or role) starts with no permissions. In other words, by default, users can
do nothing, not even change their own password. To give a user permission to do something, an
administrator must attach a permissions policy to a user. Or the administrator can add the user to a
group that has the intended permissions. When an administrator gives permissions to a group, all users
in that group are granted those permissions.
IAM policies define permissions for an action regardless of the method that you use to perform the
operation. For example, suppose that you have a policy that allows the iam:GetRole action. A user with
that policy can get role information from the AWS Management Console, the AWS CLI, or the AWS API.
Identity-based policies
Identity-based policies are JSON permissions policy documents that you can attach to an identity, such
as an IAM user, group of users, or role. These policies control what actions users and roles can perform,
on which resources, and under what conditions. To learn how to create an identity-based policy, see
Creating IAM policies in the IAM User Guide.
Identity-based policies can be further categorized as inline policies or managed policies. Inline policies
are embedded directly into a single user, group, or role. Managed policies are standalone policies that
you can attach to multiple users, groups, and roles in your AWS account. Managed policies include AWS
managed policies and customer managed policies. To learn how to choose between a managed policy or
an inline policy, see Choosing between managed policies and inline policies in the IAM User Guide.
Resource-based policies
Resource-based policies are JSON policy documents that you attach to a resource. Examples of resource-
based policies are IAM role trust policies and Amazon S3 bucket policies. In services that support resource-
based policies, service administrators can use them to control access to a specific resource. For the
resource where the policy is attached, the policy defines what actions a specified principal can perform
on that resource and under what conditions. You must specify a principal in a resource-based policy.
Principals can include accounts, users, roles, federated users, or AWS services.
784
AWS IoT Greengrass Developer Guide, Version 2
See also
Resource-based policies are inline policies that are located in that service. You can't use AWS managed
policies from IAM in a resource-based policy.
Access control lists (ACLs)
Access control lists (ACLs) control which principals (account members, users, or roles) have permissions to
access a resource. ACLs are similar to resource-based policies, although they do not use the JSON policy
document format.
Amazon S3, AWS WAF, and Amazon VPC are examples of services that support ACLs. To learn more about
ACLs, see Access control list (ACL) overview in the Amazon Simple Storage Service Developer Guide.
Other policy types
AWS supports additional, less-common policy types. These policy types can set the maximum
permissions granted to you by the more common policy types.
• Permissions boundaries – A permissions boundary is an advanced feature in which you set the
maximum permissions that an identity-based policy can grant to an IAM entity (IAM user or role).
You can set a permissions boundary for an entity. The resulting permissions are the intersection of
entity's identity-based policies and its permissions boundaries. Resource-based policies that specify
the user or role in the Principal field are not limited by the permissions boundary. An explicit deny
in any of these policies overrides the allow. For more information about permissions boundaries, see
Permissions boundaries for IAM entities in the IAM User Guide.
• Service control policies (SCPs) – SCPs are JSON policies that specify the maximum permissions for
an organization or organizational unit (OU) in AWS Organizations. AWS Organizations is a service for
grouping and centrally managing multiple AWS accounts that your business owns. If you enable all
features in an organization, then you can apply service control policies (SCPs) to any or all of your
accounts. The SCP limits permissions for entities in member accounts, including each AWS account
root user. For more information about Organizations and SCPs, see How SCPs work in the AWS
Organizations User Guide.
• Session policies – Session policies are advanced policies that you pass as a parameter when you
programmatically create a temporary session for a role or federated user. The resulting session's
permissions are the intersection of the user or role's identity-based policies and the session policies.
Permissions can also come from a resource-based policy. An explicit deny in any of these policies
overrides the allow. For more information, see Session policies in the IAM User Guide.
Multiple policy types
When multiple types of policies apply to a request, the resulting permissions are more complicated to
understand. To learn how AWS determines whether to allow a request when multiple policy types are
involved, see Policy evaluation logic in the IAM User Guide.
See also
• the section called “How AWS IoT Greengrass works with IAM” (p. 785)
• the section called “Identity-based policy examples” (p. 789)
• the section called “Troubleshooting identity and access issues” (p. 805)
How AWS IoT Greengrass works with IAM
Before you use IAM to manage access to AWS IoT Greengrass, you should understand the IAM features
that you can use with AWS IoT Greengrass.
785
AWS IoT Greengrass Developer Guide, Version 2
How AWS IoT Greengrass works with IAM
IAM feature Supported by Greengrass?
Identity-based policies with resource-level
Yes
permissions (p. 786)
Resource-based policies (p. 788) No
Access control lists (ACLs) (p. 788) No
Tags-based authorization (p. 788) Yes
Temporary credentials (p. 788) Yes
Service-linked roles (p. 788) No
Service roles (p. 788) Yes
For a high-level view of how other AWS services work with IAM, see AWS services that work with IAM in
the IAM User Guide.
Identity-based policies for AWS IoT Greengrass
With IAM identity-based policies, you can specify allowed or denied actions and resources and the
conditions under which actions are allowed or denied. AWS IoT Greengrass supports specific actions,
resources, and condition keys. To learn about all of the elements that you use in a policy, see IAM JSON
policy elements reference in the IAM User Guide.
Actions
Administrators can use AWS JSON policies to specify who has access to what. That is, which principal can
perform actions on what resources, and under what conditions.
The Action element of a JSON policy describes the actions that you can use to allow or deny access in a
policy. Policy actions usually have the same name as the associated AWS API operation. There are some
exceptions, such as permission-only actions that don't have a matching API operation. There are also
some operations that require multiple actions in a policy. These additional actions are called dependent
actions.
Include actions in a policy to grant permissions to perform the associated operation.
Policy actions for AWS IoT Greengrass use the greengrass: prefix before the action. For example,
to allow someone to use the ListCoreDevices API operation to list the core devices in their AWS
account, you include the greengrass:ListCoreDevices action in their policy. Policy statements must
include either an Action or NotAction element. AWS IoT Greengrass defines its own set of actions that
describe tasks that you can perform with this service.
To specify multiple actions in a single statement, list them between brackets ([ ]) and separate them
with commas, as follows:
"Action": [
"greengrass:action1",
"greengrass:action2",
"greengrass:action3"
]
You can use wildcards (*) to specify multiple actions. For example, to specify all actions that begin with
the word List, include the following action:
786
AWS IoT Greengrass Developer Guide, Version 2
How AWS IoT Greengrass works with IAM
"Action": "greengrass:List*"
Note
We recommend that you avoid the use of wildcards to specify all available actions for a service.
As a best practice, you should grant least privilege and narrowly scope permissions in a policy.
For more information, see the section called “Grant minimum possible permissions” (p. 815).
For the complete list of AWS IoT Greengrass actions, see Actions Defined by AWS IoT Greengrass in the
IAM User Guide.
Resources
Administrators can use AWS JSON policies to specify who has access to what. That is, which principal can
perform actions on what resources, and under what conditions.
The Resource JSON policy element specifies the object or objects to which the action applies.
Statements must include either a Resource or a NotResource element. As a best practice, specify
a resource using its Amazon Resource Name (ARN). You can do this for actions that support a specific
resource type, known as resource-level permissions.
For actions that don't support resource-level permissions, such as listing operations, use a wildcard (*) to
indicate that the statement applies to all resources.
"Resource": "*"
The following table contains the AWS IoT Greengrass resource ARNs that can be used in the Resource
element of a policy statement. For a mapping of supported resource-level permissions for AWS IoT
Greengrass actions, see Actions Defined by AWS IoT Greengrass in the IAM User Guide.
Some AWS IoT Greengrass actions (for example, some list operations), cannot be performed on a specific
resource. In those cases, you must use the wildcard alone.
"Resource": "*"
To specify multiple resource ARNs in a statement, list them between brackets ([ ]) and separate them
with commas, as follows:
"Resource": [
"resource-arn1",
"resource-arn2",
"resource-arn3"
]
For more information about ARN formats, see Amazon Resource Names (ARNs) and AWS service
namespaces in the Amazon Web Services General Reference.
Condition keys
Administrators can use AWS JSON policies to specify who has access to what. That is, which principal can
perform actions on what resources, and under what conditions.
The Condition element (or Condition block) lets you specify conditions in which a statement is in
effect. The Condition element is optional. You can create conditional expressions that use condition
operators, such as equals or less than, to match the condition in the policy with values in the request.
If you specify multiple Condition elements in a statement, or multiple keys in a single Condition
element, AWS evaluates them using a logical AND operation. If you specify multiple values for a single
787
AWS IoT Greengrass Developer Guide, Version 2
How AWS IoT Greengrass works with IAM
condition key, AWS evaluates the condition using a logical OR operation. All of the conditions must be
met before the statement's permissions are granted.
You can also use placeholder variables when you specify conditions. For example, you can grant an IAM
user permission to access a resource only if it is tagged with their IAM user name. For more information,
see IAM policy elements: variables and tags in the IAM User Guide.
AWS supports global condition keys and service-specific condition keys. To see all AWS global condition
keys, see AWS global condition context keys in the IAM User Guide.
Examples
To view examples of AWS IoT Greengrass identity-based policies, see the section called “Identity-based
policy examples” (p. 789).
Resource-based policies for AWS IoT Greengrass
AWS IoT Greengrass does not support resource-based policies (p. 784).
Access control lists (ACLs)
AWS IoT Greengrass does not support ACLs (p. 785).
Authorization based on AWS IoT Greengrass tags
You can attach tags to supported AWS IoT Greengrass resources or pass tags in a request to AWS IoT
Greengrass. To control access based on tags, you provide tag information in the Condition element of
a policy using the aws:ResourceTag/${TagKey}, aws:RequestTag/${TagKey}, or aws:TagKeys
condition keys. For more information, see Tag your resources (p. 919).
IAM roles for AWS IoT Greengrass
An IAM role is an entity within your AWS account that has specific permissions.
Using temporary credentials with AWS IoT Greengrass
Temporary credentials are used to sign in with federation, assume an IAM role, or to assume a cross-
account role. You obtain temporary security credentials by calling AWS STS API operations such as
AssumeRole or GetFederationToken.
On the Greengrass core, temporary credentials for the device role (p. 790) are made available to
Greengrass components. If your components use the AWS SDK, you don't need to add logic to obtain the
credentials because the AWS SDK does this for you.
Service-linked roles
AWS IoT Greengrass does not support service-linked roles.
Service roles
This feature allows a service to assume a service role on your behalf. This role allows the service to
access resources in other services to complete an action on your behalf. Service roles appear in your
IAM account and are owned by the account. This means that an IAM administrator can change the
permissions for this role. However, doing so might break the functionality of the service.
AWS IoT Greengrass core devices use a service role to allow Greengrass components and Lambda
functions to access some of your AWS resources on your behalf. For more information, see the section
called “Authorize core devices to interact with AWS services” (p. 790).
788
AWS IoT Greengrass Developer Guide, Version 2
Identity-based policy examples
AWS IoT Greengrass uses a service role to access some of your AWS resources on your behalf. For more
information, see Greengrass service role (p. 796).
Identity-based policy examples for AWS IoT
Greengrass
By default, IAM users and roles don't have permission to create or modify AWS IoT Greengrass resources.
They also can't perform tasks using the AWS Management Console, AWS CLI, or AWS API. An IAM
administrator must create IAM policies that grant users and roles permission to perform specific API
operations on the specified resources they need. The administrator must then attach those policies to
the IAM users or groups that require those permissions.
Policy best practices
Identity-based policies are very powerful. They determine whether someone can create, access, or delete
AWS IoT Greengrass resources in your account. These actions can incur costs for your AWS account. When
you create or edit identity-based policies, follow these guidelines and recommendations:
• Get started using AWS managed policies – To start using AWS IoT Greengrass quickly, use AWS
managed policies to give your employees the permissions they need. These policies are already
available in your account and are maintained and updated by AWS. For more information, see Get
started using permissions with AWS managed policies in the IAM User Guide.
• Grant least privilege – When you create custom policies, grant only the permissions required
to perform a task. Start with a minimum set of permissions and grant additional permissions as
necessary. Doing so is more secure than starting with permissions that are too lenient and then trying
to tighten them later. For more information, see Grant least privilege in the IAM User Guide.
• Enable MFA for sensitive operations – For extra security, require IAM users to use multi-factor
authentication (MFA) to access sensitive resources or API operations. For more information, see Using
multi-factor authentication (MFA) in AWS in the IAM User Guide.
• Use policy conditions for extra security – To the extent that it's practical, define the conditions under
which your identity-based policies allow access to a resource. For example, you can write conditions to
specify a range of allowable IP addresses that a request must come from. You can also write conditions
to allow requests only within a specified date or time range, or to require the use of SSL or MFA. For
more information, see IAM JSON policy elements: Condition in the IAM User Guide.
Policy examples
The following example customer-defined policies grant permissions for common scenarios.
Examples
• Allow users to view their own permissions (p. 789)
To learn how to create an IAM identity-based policy using these example JSON policy documents, see
Creating policies on the JSON tab in the IAM User Guide.
Allow users to view their own permissions
This example shows how you might create a policy that allows IAM users to view the inline and managed
policies that are attached to their user identity. This policy includes permissions to complete this action
on the console or programmatically using the AWS CLI or AWS API.
789
AWS IoT Greengrass Developer Guide, Version 2
Authorize core devices to interact with AWS services
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ViewOwnUserInfo",
"Effect": "Allow",
"Action": [
"iam:GetUserPolicy",
"iam:ListGroupsForUser",
"iam:ListAttachedUserPolicies",
"iam:ListUserPolicies",
"iam:GetUser"
],
"Resource": ["arn:aws:iam::*:user/${aws:username}"]
},
{
"Sid": "NavigateInConsole",
"Effect": "Allow",
"Action": [
"iam:GetGroupPolicy",
"iam:GetPolicyVersion",
"iam:GetPolicy",
"iam:ListAttachedGroupPolicies",
"iam:ListGroupPolicies",
"iam:ListPolicyVersions",
"iam:ListPolicies",
"iam:ListUsers"
],
"Resource": "*"
}
]
}
Authorize core devices to interact with AWS services
AWS IoT Greengrass core devices use the AWS IoT Core credentials provider to authorize calls to AWS
services. The AWS IoT Core credentials provider enables devices to use their X.509 certificates as the
unique device identity to authenticate AWS requests. This eliminates the need to store an AWS access key
ID and secret access key on your AWS IoT Greengrass core devices. For more information, see Authorizing
direct calls to AWS services in the AWS IoT Core Developer Guide.
When you run the AWS IoT Greengrass Core software, you can choose to provision the AWS resources
that the core device requires. This includes the AWS Identity and Access Management (IAM) role that
your core device assumes through the AWS IoT Core credentials provider. Use the --provision true
argument to configure a role and policies that allow the core device to get temporary AWS credentials.
This argument also configures an AWS IoT role alias that points to this IAM role. You can specify the
name of the IAM role and AWS IoT role alias to use. If you specify --provision true without these
other name parameters, the Greengrass core device creates and uses the following default resources:
• IAM role: GreengrassV2TokenExchangeRole
This role has a policy named GreengrassV2TokenExchangeRoleAccess and a trust relationship
that allows credentials.iot.amazonaws.com to assume the role. The policy includes the
minimum permissions for the core device.
Important
This policy doesn't include access to files in S3 buckets. You must add permissions to the role
to allow core devices to retrieve component artifacts from S3 buckets. For more information,
see Allow access to S3 buckets for component artifacts (p. 792).
• AWS IoT role alias: GreengrassV2TokenExchangeRoleAlias
This role alias refers to the IAM role.
790
AWS IoT Greengrass Developer Guide, Version 2
Authorize core devices to interact with AWS services
For more information, see Step 3: Install the AWS IoT Greengrass Core software (p. 35).
You can also set the role alias for an existing core device. To do so, configure the iotRoleAlias
configuration parameter of the Greengrass nucleus component (p. 181).
You can acquire temporary AWS credentials for this IAM role to perform AWS operations in your custom
components. For more information, see Interact with AWS services (p. 454).
Topics
• Service role permissions for core devices (p. 791)
• Allow access to S3 buckets for component artifacts (p. 792)
Service role permissions for core devices
The role allows the following service to assume the role:
• credentials.iot.amazonaws.com
If you use the AWS IoT Greengrass Core software to create this role, it uses the following permissions
policy to allow core devices to connect and send logs to AWS. The policy's name defaults to the name of
the IAM role ending with Access. For example, if you use the default IAM role name, then this policy's
name is GreengrassV2TokenExchangeRoleAccess.
Greengrass nucleus v2.5.0 and later
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:DescribeLogStreams",
"s3:GetBucketLocation"
],
"Resource": "*"
}
]
}
v2.4.x
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:DescribeCertificate",
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:DescribeLogStreams",
"s3:GetBucketLocation"
],
"Resource": "*"
}
]
791
AWS IoT Greengrass Developer Guide, Version 2
Authorize core devices to interact with AWS services
Earlier than v2.4.0
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:DescribeCertificate",
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:DescribeLogStreams",
"iot:Connect",
"iot:Publish",
"iot:Subscribe",
"iot:Receive",
"s3:GetBucketLocation"
],
"Resource": "*"
}
]
}
Allow access to S3 buckets for component artifacts
The default core device role doesn't allow core devices to access S3 buckets. To deploy components
that have artifacts in S3 buckets, you must add the s3:GetObject permission to allow core devices to
download component artifacts. You can add a new policy to the core device role to grant this permission.
To add a policy that allows access to component artifacts in Amazon S3
1. Create a file called component-artifact-policy.json and copy the following JSON into the
file. This policy allows access to all files in an S3 bucket. Replace DOC-EXAMPLE-BUCKET with the
name of the S3 bucket to allow the core device to access.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject"
],
"Resource": "arn:aws:s3:::DOC-EXAMPLE-BUCKET/*"
}
]
}
2. Run the following command to create the policy from the policy document in component-
artifact-policy.json.
Linux or Unix
aws iam create-policy \
--policy-name MyGreengrassV2ComponentArtifactPolicy \
--policy-document file://component-artifact-policy.json
792
AWS IoT Greengrass Developer Guide, Version 2
Minimal IAM policy for installer to provision resources
Windows Command Prompt (CMD)
aws iam create-policy ^
--policy-name MyGreengrassV2ComponentArtifactPolicy ^
--policy-document file://component-artifact-policy.json
PowerShell
aws iam create-policy `
--policy-name MyGreengrassV2ComponentArtifactPolicy `
--policy-document file://component-artifact-policy.json
Copy the policy Amazon Resource Name (ARN) from the policy metadata in the output. You use this
ARN to attach this policy to the core device role in the next step.
3. Run the following command to attach the policy to the core device role. Replace
GreengrassV2TokenExchangeRole with the name of the role that you specified when you ran
the AWS IoT Greengrass Core software. Then, replace the policy ARN with the ARN from the previous
step.
Linux or Unix
aws iam attach-role-policy \
--role-name GreengrassV2TokenExchangeRole \
--policy-arn
arn:aws:iam::123456789012:policy/MyGreengrassV2ComponentArtifactPolicy
Windows Command Prompt (CMD)
aws iam attach-role-policy ^
--role-name GreengrassV2TokenExchangeRole ^
--policy-arn
arn:aws:iam::123456789012:policy/MyGreengrassV2ComponentArtifactPolicy
PowerShell
aws iam attach-role-policy `
--role-name GreengrassV2TokenExchangeRole `
--policy-arn
arn:aws:iam::123456789012:policy/MyGreengrassV2ComponentArtifactPolicy
If the command has no output, it succeeded, and your core device can access artifacts that you
upload to this S3 bucket.
Minimal IAM policy for installer to provision resources
When you install the AWS IoT Greengrass Core software, you can provision required AWS resources, such
as an AWS IoT thing and an IAM role for your device. You can also deploy local development tools to the
device. The installer requires AWS credentials so that it can perform these actions in your AWS account.
For more information, see Install the AWS IoT Greengrass Core software (p. 67).
The following example policy includes the minimum set of actions that the installer requires
to provision these resources. These permissions are required if you specify the --provision
793
AWS IoT Greengrass Developer Guide, Version 2
Minimal IAM policy for installer to provision resources
argument for the installer. Replace account-id with your AWS account ID, and replace
GreengrassV2TokenExchangeRole with the name of the token exchange role that you specify with
the --tes-role-name installer argument (p. 126).
Note
The DeployDevTools policy statement is required only if you specify the --deploy-dev-
tools argument for the installer.
Greengrass nucleus v2.5.0 and later
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "CreateTokenExchangeRole",
"Effect": "Allow",
"Action": [
"iam:AttachRolePolicy",
"iam:CreatePolicy",
"iam:CreateRole",
"iam:GetPolicy",
"iam:GetRole",
"iam:PassRole"
],
"Resource": [
"arn:aws:iam::account-id:role/GreengrassV2TokenExchangeRole",
"arn:aws:iam::account-id:policy/GreengrassV2TokenExchangeRoleAccess"
]
},
{
"Sid": "CreateIoTResources",
"Effect": "Allow",
"Action": [
"iot:AddThingToThingGroup",
"iot:AttachPolicy",
"iot:AttachThingPrincipal",
"iot:CreateKeysAndCertificate",
"iot:CreatePolicy",
"iot:CreateRoleAlias",
"iot:CreateThing",
"iot:CreateThingGroup",
"iot:DescribeEndpoint",
"iot:DescribeRoleAlias",
"iot:DescribeThingGroup",
"iot:GetPolicy"
],
"Resource": "*"
},
{
"Sid": "DeployDevTools",
"Effect": "Allow",
"Action": [
"greengrass:CreateDeployment",
"iot:CancelJob",
"iot:CreateJob",
"iot:DeleteThingShadow",
"iot:DescribeJob",
"iot:DescribeThing",
"iot:DescribeThingGroup",
"iot:GetThingShadow",
"iot:UpdateJob",
"iot:UpdateThingShadow"
],
"Resource": "*"
}
794
AWS IoT Greengrass Developer Guide, Version 2
Minimal IAM policy for installer to provision resources
]
}
Earlier than v2.5.0
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "CreateTokenExchangeRole",
"Effect": "Allow",
"Action": [
"iam:AttachRolePolicy",
"iam:CreatePolicy",
"iam:CreateRole",
"iam:GetPolicy",
"iam:GetRole",
"iam:PassRole"
],
"Resource": [
"arn:aws:iam::account-id:role/GreengrassV2TokenExchangeRole",
"arn:aws:iam::account-id:policy/GreengrassV2TokenExchangeRoleAccess",
"arn:aws:iam::aws:policy/GreengrassV2TokenExchangeRoleAccess"
]
},
{
"Sid": "CreateIoTResources",
"Effect": "Allow",
"Action": [
"iot:AddThingToThingGroup",
"iot:AttachPolicy",
"iot:AttachThingPrincipal",
"iot:CreateKeysAndCertificate",
"iot:CreatePolicy",
"iot:CreateRoleAlias",
"iot:CreateThing",
"iot:CreateThingGroup",
"iot:DescribeEndpoint",
"iot:DescribeRoleAlias",
"iot:DescribeThingGroup",
"iot:GetPolicy"
],
"Resource": "*"
},
{
"Sid": "DeployDevTools",
"Effect": "Allow",
"Action": [
"greengrass:CreateDeployment",
"iot:CancelJob",
"iot:CreateJob",
"iot:DeleteThingShadow",
"iot:DescribeJob",
"iot:DescribeThing",
"iot:DescribeThingGroup",
"iot:GetThingShadow",
"iot:UpdateJob",
"iot:UpdateThingShadow"
],
"Resource": "*"
}
]
}
795
AWS IoT Greengrass Developer Guide, Version 2
Greengrass service role
Greengrass service role
The Greengrass service role is an AWS Identity and Access Management (IAM) service role that authorizes
AWS IoT Greengrass to access resources from AWS services on your behalf. This role makes it possible
for AWS IoT Greengrass to verify the identity of client devices and manage core device connectivity
information.
Note
AWS IoT Greengrass V1 also uses this role to perform essential tasks. For more information, see
Greengrass service role in the AWS IoT Greengrass V1 Developer Guide.
To allow AWS IoT Greengrass to access your resources, the Greengrass service role must be associated
with your AWS account and specify AWS IoT Greengrass as a trusted entity. The role must include the
AWSGreengrassResourceAccessRolePolicy managed policy or a custom policy that defines equivalent
permissions for the AWS IoT Greengrass features that you use. AWS maintains this policy, which defines
the set of permissions that AWS IoT Greengrass uses to access your AWS resources.
You can reuse the same Greengrass service role across AWS Regions, but you must associate it with your
account in every AWS Region where you use AWS IoT Greengrass. If the service role isn't configured
in the current AWS Region, core devices fail to verify client devices and fail to update connectivity
information.
The following sections describe how to create and manage the Greengrass service role with the AWS
Management Console or AWS CLI.
Topics
• Manage the Greengrass service role (console) (p. 796)
• Manage the Greengrass service role (CLI) (p. 798)
• See also (p. 801)
Note
In addition to the service role that authorizes service-level access, you assign a token exchange
role to Greengrass core devices. The token exchange role is a separate IAM role that controls
how Greengrass components and Lambda functions on the core device can access AWS services.
For more information, see Authorize core devices to interact with AWS services (p. 790).
Manage the Greengrass service role (console)
The AWS IoT console makes it easy to manage your Greengrass service role. For example, when you
configure client device discovery for a core device, the console checks whether your AWS account is
attached to a Greengrass service role in the current AWS Region. If not, the console can create and
configure a service role for you. For more information, see the section called “Create the Greengrass
service role” (p. 797).
Role management tasks
Note
The user who is signed in to the console must have permissions to view, create, or change the
service role.
Find your Greengrass service role (console)
Use the following steps to find the service role that AWS IoT Greengrass uses in the current AWS Region.
1. Navigate to the AWS IoT console.
2. In the navigation pane, choose Settings.
796
AWS IoT Greengrass Developer Guide, Version 2
Greengrass service role
3. Scroll to the Greengrass service role section to see your service role and its policies.
If you don't see a service role, the console can create or configure one for you. For more information,
see Create the Greengrass service role (p. 797).
Create the Greengrass service role (console)
The console can create and configure a default Greengrass service role for you. This role has the
following properties.
Property Value
Name Greengrass_ServiceRole
Trusted entity AWS service: greengrass
Policy AWSGreengrassResourceAccessRolePolicy
Note
If you create this role with the AWS IoT Greengrass V1 device setup script, the role name is
GreengrassServiceRole_random-string.
When you configure client device discovery for a core device, the console checks whether a Greengrass
service role is associated with your AWS account in the current AWS Region. If not, the console prompts
you to allow AWS IoT Greengrass to read and write to AWS services on your behalf.
If you grant permission, the console checks whether a role named Greengrass_ServiceRole exists in
your AWS account.
• If the role exists, the console attaches the service role to your AWS account in the current AWS Region.
• If the role doesn't exist, the console creates a default Greengrass service role and attaches it to your
AWS account in the current AWS Region.
Note
If you want to create a service role with custom role policies, use the IAM console to create
or modify the role. For more information, see Creating a role to delegate permissions to
an AWS service or Modifying a role in the IAM User Guide. Make sure that the role grants
permissions that are equivalent to the AWSGreengrassResourceAccessRolePolicy
managed policy for the features and resources that you use. We recommend that you also
include the aws:SourceArn and aws:SourceAccount global condition context keys in
your trust policy to help prevent the confused deputy security problem. The condition context
keys restrict access to allow only those requests that come from the specified account and
Greengrass workspace. For more information about the confused deputy problem, see Cross-
service confused deputy prevention (p. 805).
If you create a service role, return to the AWS IoT console and attach the role to your AWS
account. You can do this under Greengrass service role on the Settings page.
Change the Greengrass service role (console)
Use the following procedure to choose a different Greengrass service role to attach to your AWS account
in the AWS Region currently selected in the console.
1. Navigate to the AWS IoT console.
2. In the navigation pane, choose Settings.
3. Under Greengrass service role, choose Change role.
797
AWS IoT Greengrass Developer Guide, Version 2
Greengrass service role
The Update Greengrass service role dialog box opens and shows the IAM roles in your AWS account
that define AWS IoT Greengrass as a trusted entity.
4. Choose the Greengrass service role to attach.
5. Choose Attach role.
Detach the Greengrass service role (console)
Use the following procedure to detach the Greengrass service role from your AWS account in the current
AWS Region. This revokes permissions for AWS IoT Greengrass to access AWS services in the current AWS
Region.
Important
Detaching the service role might interrupt active operations.
1. Navigate to the AWS IoT console.
2. In the navigation pane, choose Settings.
3. Under Greengrass service role, choose Detach role.
4. In the confirmation dialog box, choose Detach.
Note
If you no longer need the role, you can delete it in the IAM console. For more information, see
Deleting roles or instance profiles in the IAM User Guide.
Other roles might allow AWS IoT Greengrass to access your resources. To find all roles that allow
AWS IoT Greengrass to assume permissions on your behalf, in the IAM console, on the Roles
page, look for roles that include AWS service: greengrass in the Trusted entities column.
Manage the Greengrass service role (CLI)
In the following procedures, we assume that the AWS Command Line Interface is installed and
configured to use your AWS account. For more information, see Installing, updating, and uninstalling the
AWS CLI and Configuring the AWS CLI in the AWS Command Line Interface User Guide.
You can use the AWS CLI for the following role management tasks:
Topics
• Get the Greengrass service role (CLI) (p. 798)
• Create the Greengrass service role (CLI) (p. 799)
• Remove the Greengrass service role (CLI) (p. 800)
Note
AWS IoT Greengrass V2 uses AWS IoT Greengrass V1 API operations to manage the Greengrass
service role.
Get the Greengrass service role (CLI)
Use the following procedure to find out if a Greengrass service role is associated with your AWS account
in an AWS Region.
• Get the service role. Replace region with your AWS Region (for example, us-west-2).
aws greengrass get-service-role-for-account --region region
798
AWS IoT Greengrass Developer Guide, Version 2
Greengrass service role
If a Greengrass service role is already associated with your account, the request returns the following
role metadata.
{
"AssociatedAt": "timestamp",
"RoleArn": "arn:aws:iam::account-id:role/path/role-name"
}
If the request doesn't return role metadata, then you must create the service role (if it doesn't exist)
and associate it with your account in the AWS Region.
Create the Greengrass service role (CLI)
Use the following steps to create a role and associate it with your AWS account.
To create the service role using IAM
1. Create a role with a trust policy that allows AWS IoT Greengrass to assume the role. This example
creates a role named Greengrass_ServiceRole, but you can use a different name. We
recommend that you also include the aws:SourceArn and aws:SourceAccount global condition
context keys in your trust policy to help prevent the confused deputy security problem. The condition
context keys restrict access to allow only those requests that come from the specified account and
Greengrass workspace. For more information about the confused deputy problem, see Cross-service
confused deputy prevention (p. 805).
Linux or Unix
aws iam create-role --role-name Greengrass_ServiceRole --assume-role-policy-
document '{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "greengrass.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"ArnLike": {
"aws:SourceArn": "arn:aws:greengrass:region:account-id:*"
},
"StringEquals": {
"aws:SourceAccount": "account-id"
}
}
}
]
}'
Windows Command Prompt (CMD)
aws iam create-role --role-name Greengrass_ServiceRole --assume-role-
policy-document "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect
\":\"Allow\",\"Principal\":{\"Service\":\"greengrass.amazonaws.com\"},
\"Action\":\"sts:AssumeRole\",\"Condition\":{\"ArnLike\":{\"aws:SourceArn\":
\"arn:aws:greengrass:region:account-id:*\"},\"StringEquals\":{\"aws:SourceAccount
\":\"account-id\"}}}]}"
799
AWS IoT Greengrass Developer Guide, Version 2
Greengrass service role
PowerShell
aws iam create-role --role-name Greengrass_ServiceRole --assume-role-policy-
document '{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "greengrass.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"ArnLike": {
"aws:SourceArn": "arn:aws:greengrass:region:account-id:*"
},
"StringEquals": {
"aws:SourceAccount": "account-id"
}
}
}
]
}'
2. Copy the role ARN from the role metadata in the output. You use the ARN to associate the role with
your account.
3. Attach the AWSGreengrassResourceAccessRolePolicy policy to the role.
aws iam attach-role-policy --role-name Greengrass_ServiceRole --policy-arn
arn:aws:iam::aws:policy/service-role/AWSGreengrassResourceAccessRolePolicy
To associate the service role with your AWS account
• Associate the role with your account. Replace role-arn with the service role ARN and region with
your AWS Region (for example, us-west-2).
aws greengrass associate-service-role-to-account --role-arn role-arn --region region
If successful, the request returns the following response.
{
"AssociatedAt": "timestamp"
}
Remove the Greengrass service role (CLI)
Use the following steps to disassociate the Greengrass service role from your AWS account.
• Disassociate the service role from your account. Replace region with your AWS Region (for
example, us-west-2).
aws greengrass disassociate-service-role-from-account --region region
If successful, the following response is returned.
800
AWS IoT Greengrass Developer Guide, Version 2
AWS managed policies
{
"DisassociatedAt": "timestamp"
}
Note
You should delete the service role if you're not using it in any AWS Region. First use delete-
role-policy to detach the AWSGreengrassResourceAccessRolePolicy managed
policy from the role, and then use delete-role to delete the role. For more information, see
Deleting roles or instance profiles in the IAM User Guide.
See also
• Creating a role to delegate permissions to an AWS service in the IAM User Guide
• Modifying a role in the IAM User Guide
• Deleting roles or instance profiles in the IAM User Guide
• AWS IoT Greengrass commands in the AWS CLI Command Reference
• associate-service-role-to-account
• disassociate-service-role-from-account
• get-service-role-for-account
• IAM commands in the AWS CLI Command Reference
• attach-role-policy
• create-role
• delete-role
• delete-role-policy
AWS managed policies for AWS IoT Greengrass
To add permissions to users, groups, and roles, it is easier to use AWS managed policies than to write
policies yourself. It takes time and expertise to create IAM customer managed policies that provide your
team with only the permissions they need. To get started quickly, you can use our AWS managed policies.
These policies cover common use cases and are available in your AWS account. For more information
about AWS managed policies, see AWS managed policies in the IAM User Guide.
AWS services maintain and update AWS managed policies. You can't change the permissions in AWS
managed policies. Services occasionally add additional permissions to an AWS managed policy to
support new features. This type of update affects all identities (users, groups, and roles) where the policy
is attached. Services are most likely to update an AWS managed policy when a new feature is launched
or when new operations become available. Services do not remove permissions from an AWS managed
policy, so policy updates won't break your existing permissions.
Additionally, AWS supports managed policies for job functions that span multiple services. For example,
the ViewOnlyAccess AWS managed policy provides read-only access to many AWS services and
resources. When a service launches a new feature, AWS adds read-only permissions for new operations
and resources. For a list and descriptions of job function policies, see AWS managed policies for job
functions in the IAM User Guide.
Topics
• AWS managed policy: AWSGreengrassFullAccess (p. 802)
• AWS managed policy: AWSGreengrassReadOnlyAccess (p. 802)
• AWS managed policy: AWSGreengrassResourceAccessRolePolicy (p. 803)
801
AWS IoT Greengrass Developer Guide, Version 2
AWS managed policies
• AWS IoT Greengrass updates to AWS managed policies (p. 805)
AWS managed policy: AWSGreengrassFullAccess
You can attach the AWSGreengrassFullAccess policy to your IAM identities.
This policy grants administrative permissions that allow a principal full access to all AWS IoT Greengrass
actions.
Permissions details
This policy includes the following permissions:
• greengrass – Allows principals full access to all AWS IoT Greengrass actions.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"greengrass:*"
],
"Resource": "*"
}
]
}
AWS managed policy: AWSGreengrassReadOnlyAccess
You can attach the AWSGreengrassReadOnlyAccess policy to your IAM identities.
This policy grants read-only permissions that allow a principal to view, but not modify, information in
AWS IoT Greengrass. For example, principals with these permissions can view the list of components
deployed to a Greengrass core device, but can't create a deployment to change the components that run
on that device.
Permissions details
This policy includes the following permissions:
• greengrass – Allows principals to perform actions that return either a list of items or details about
an item. This includes API operations that start with List or Get.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"greengrass:List*",
"greengrass:Get*"
],
"Resource": "*"
}
]
}
802
AWS IoT Greengrass Developer Guide, Version 2
AWS managed policies
AWS managed policy: AWSGreengrassResourceAccessRolePolicy
You can attach the AWSGreengrassResourceAccessRolePolicy policy to your IAM entities. AWS IoT
Greengrass also attaches this policy to a service role that allows AWS IoT Greengrass to perform actions
on your behalf. For more information, see Greengrass service role (p. 796).
This policy grants administrative permissions that allow AWS IoT Greengrass to perform essential tasks,
such as retrieving your Lambda functions, managing AWS IoT device shadows, and verifying Greengrass
client devices.
Permissions details
This policy includes the following permissions.
• greengrass – Manage Greengrass resources.
• iot (*Shadow) – Manage AWS IoT shadows that have special identifiers in their names. These
permissions are required so that AWS IoT Greengrass can communicate with core devices.
• iot (DescribeThing and DescribeCertificate) – Retrieve information about AWS IoT things and
certificates. These permissions are required so that AWS IoT Greengrass can verify client devices that
connect to a core device. For more information, see Interact with local IoT devices (p. 638).
• lambda – Retrieve information about AWS Lambda functions. This permission is required so that AWS
IoT Greengrass V1 can deploy Lambda functions to Greengrass cores. For more information, see Run
Lambda function on the AWS IoT Greengrass core in the AWS IoT Greengrass V1 Developer Guide.
• secretsmanager – Retrieve the value of AWS Secrets Manager secrets whose names start with
greengrass-. This permission is required so that AWS IoT Greengrass V1 can deploy Secrets Manager
secrets to Greengrass cores. For more information, see Deploy secrets to the AWS IoT Greengrass core
in the AWS IoT Greengrass V1 Developer Guide.
• s3 – Retrieve files objects from S3 buckets whose names contain greengrass or sagemaker. These
permissions are required so that AWS IoT Greengrass V1 can deploy machine learning resources
that you store in S3 buckets. For more information, see Machine learning resources in the AWS IoT
Greengrass V1 Developer Guide.
• sagemaker – Retrieve information about Amazon SageMaker machine learning inference models. This
permission is required so that AWS IoT Greengrass V1 can deploy ML models to Greengrass cores. For
more information, see Perform machine learning inference in the AWS IoT Greengrass V1 Developer
Guide.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowGreengrassAccessToShadows",
"Action": [
"iot:DeleteThingShadow",
"iot:GetThingShadow",
"iot:UpdateThingShadow"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:*:*:thing/GG_*",
"arn:aws:iot:*:*:thing/*-gcm",
"arn:aws:iot:*:*:thing/*-gda",
"arn:aws:iot:*:*:thing/*-gci"
]
},
{
"Sid": "AllowGreengrassToDescribeThings",
"Action": [
803
AWS IoT Greengrass Developer Guide, Version 2
AWS managed policies
"iot:DescribeThing"
],
"Effect": "Allow",
"Resource": "arn:aws:iot:*:*:thing/*"
},
{
"Sid": "AllowGreengrassToDescribeCertificates",
"Action": [
"iot:DescribeCertificate"
],
"Effect": "Allow",
"Resource": "arn:aws:iot:*:*:cert/*"
},
{
"Sid": "AllowGreengrassToCallGreengrassServices",
"Action": [
"greengrass:*"
],
"Effect": "Allow",
"Resource": "*"
},
{
"Sid": "AllowGreengrassToGetLambdaFunctions",
"Action": [
"lambda:GetFunction",
"lambda:GetFunctionConfiguration"
],
"Effect": "Allow",
"Resource": "*"
},
{
"Sid": "AllowGreengrassToGetGreengrassSecrets",
"Action": [
"secretsmanager:GetSecretValue"
],
"Effect": "Allow",
"Resource": "arn:aws:secretsmanager:*:*:secret:greengrass-*"
},
{
"Sid": "AllowGreengrassAccessToS3Objects",
"Action": [
"s3:GetObject"
],
"Effect": "Allow",
"Resource": [
"arn:aws:s3:::*Greengrass*",
"arn:aws:s3:::*GreenGrass*",
"arn:aws:s3:::*greengrass*",
"arn:aws:s3:::*Sagemaker*",
"arn:aws:s3:::*SageMaker*",
"arn:aws:s3:::*sagemaker*"
]
},
{
"Sid": "AllowGreengrassAccessToS3BucketLocation",
"Action": [
"s3:GetBucketLocation"
],
"Effect": "Allow",
"Resource": "*"
},
{
"Sid": "AllowGreengrassAccessToSageMakerTrainingJobs",
"Action": [
"sagemaker:DescribeTrainingJob"
],
804
AWS IoT Greengrass Developer Guide, Version 2
Cross-service confused deputy prevention
"Effect": "Allow",
"Resource": [
"arn:aws:sagemaker:*:*:training-job/*"
]
}
]
}
AWS IoT Greengrass updates to AWS managed policies
You can view details about updates to AWS managed policies for AWS IoT Greengrass from the time this
service began tracking these changes. For automatic alerts about changes to this page, subscribe to the
RSS feed on the AWS IoT Greengrass V2 document history page (p. 922).
Change Description Date
AWS IoT Greengrass started AWS IoT Greengrass started July 2, 2021
tracking changes tracking changes for its AWS
managed policies.
Cross-service confused deputy prevention
The confused deputy problem is a security issue where an entity that doesn't have permission to perform
an action can coerce a more-privileged entity to perform the action. In AWS, cross-service impersonation
can result in the confused deputy problem. Cross-service impersonation can occur when one service (the
calling service) calls another service (the called service). The calling service can be manipulated to use its
permissions to act on another customer's resources in a way it should not otherwise have permission to
access. To prevent this, AWS provides tools that help you protect your data for all services with service
principals that have been given access to resources in your account.
We recommend using the aws:SourceArn and aws:SourceAccount global condition context keys in
resource policies to limit the permissions that AWS IoT Greengrass gives another service to the resource.
If you use both global condition context keys, the aws:SourceAccount value and the account in the
aws:SourceArn value must use the same account ID when used in the same policy statement.
The value of aws:SourceArn must be the Greengrass customer resource that is associated with the
sts:AssumeRole request.
The most effective way to protect against the confused deputy problem is to use the aws:SourceArn
global condition context key with the full ARN of the resource. If you don't know the full ARN
of the resource or if you are specifying multiple resources, use the aws:SourceArn global
context condition key with wildcards (*) for the unknown portions of the ARN. For example,
arn:aws:greengrass::account-id:*.
For an example of a policy that uses the aws:SourceArn and aws:SourceAccount global condition
context keys, see Create the Greengrass service role (p. 799).
Troubleshooting identity and access issues for AWS
IoT Greengrass
Use the following information to help you diagnose and fix common issues that you might encounter
when working with AWS IoT Greengrass and IAM.
Issues
805
AWS IoT Greengrass Developer Guide, Version 2
Troubleshooting identity and access issues
• I'm not authorized to perform an action in AWS IoT Greengrass (p. 806)
• I'm not authorized to perform iam:PassRole (p. 806)
• I'm an administrator and want to allow others to access AWS IoT Greengrass (p. 806)
• I want to allow people outside of my AWS account to access my AWS IoT Greengrass
resources (p. 807)
For general troubleshooting help, see Troubleshooting (p. 911).
I'm not authorized to perform an action in AWS IoT Greengrass
If you receive an error that states you're not authorized to perform an action, you must contact your
administrator for assistance. Your administrator is the person who provided you with your user name and
password.
The following example error occurs when the mateojackson IAM user tries to view details about a core
device, but does not have greengrass:GetCoreDevice permissions.
User: arn:aws:iam::123456789012:user/mateojackson is not authorized to
perform: greengrass:GetCoreDevice on resource: arn:aws:greengrass:us-
west-2:123456789012:coreDevices/MyGreengrassCore
In this case, Mateo asks his administrator to update his policies to allow him to access the
arn:aws:greengrass:us-west-2:123456789012:coreDevices/MyGreengrassCore resource
using the greengrass:GetCoreDevice action.
The following are general IAM issues that you might encounter when working with AWS IoT Greengrass.
I'm not authorized to perform iam:PassRole
If you receive an error that you're not authorized to perform the iam:PassRole action, then you must
contact your administrator for assistance. Your administrator is the person that provided you with your
user name and password. Ask that person to update your policies to allow you to pass a role to AWS IoT
Greengrass.
Some AWS services allow you to pass an existing role to that service, instead of creating a new service
role or service-linked role. To do this, you must have permissions to pass the role to the service.
The following example error occurs when an IAM user named marymajor tries to use the console to
perform an action in AWS IoT Greengrass. However, the action requires the service to have permissions
granted by a service role. Mary does not have permissions to pass the role to the service.
User: arn:aws:iam::123456789012:user/marymajor is not authorized to perform: iam:PassRole
In this case, Mary asks her administrator to update her policies to allow her to perform the
iam:PassRole action.
I'm an administrator and want to allow others to access AWS IoT
Greengrass
To allow others to access AWS IoT Greengrass, you must create an IAM entity (user or role) for the person
or application that needs access. They will use the credentials for that entity to access AWS. You must
then attach a policy to the entity that grants them the correct permissions in AWS IoT Greengrass.
To get started right away, see Creating your first IAM delegated user and group in the IAM User Guide.
806
AWS IoT Greengrass Developer Guide, Version 2
Allow device traffic through a proxy or firewall
I want to allow people outside of my AWS account to access my
AWS IoT Greengrass resources
You can create an IAM role that users in other accounts or people outside of your organization can use to
access your AWS resources. You can specify the who is trusted to assume the role. For more information,
see Providing access to an IAM user in another AWS account that you own and Providing access to AWS
accounts owned by third parties in the IAM User Guide.
AWS IoT Greengrass doesn't support cross-account access based on resource-based policies or access
control lists (ACLs).
Allow device traffic through a proxy or firewall
Greengrass core devices and Greengrass components perform outbound requests to AWS services and
other websites. As a security measure, you might limit outbound traffic to a small range of endpoints and
ports. You can use the following information about endpoints and ports to limit device traffic through a
proxy or firewall. For more information about how to configure a core device to use a proxy, see Connect
on port 443 or through a network proxy (p. 165).
Topics
• Endpoints for basic operation (p. 807)
• Endpoints for installation with automatic provisioning (p. 809)
• Endpoints for AWS-provided components (p. 810)
Endpoints for basic operation
Greengrass core devices use the following endpoints and ports for basic operation.
Endpoint Port Required Description
greengrass- 8443 or 443 Yes Used for
ats.iot.region.amazonaws.com data plane
operations,
such as
installing
deployments
and working
with client
devices.
prefix- MQTT: 8883 or 443 Yes Used for
ats.iot.region.amazonaws.com data plane
HTTPS: 8443 or 443 operations
for device
management,
such as
MQTT
communication
and shadow
sync with
AWS IoT
Core.
807
AWS IoT Greengrass Developer Guide, Version 2
Endpoints for basic operation
Endpoint Port Required Description
443
prefix.credentials.iot.region.amazonaws.com Yes Used to
acquire AWS
credentials,
which the
core device
uses to
download
component
artifacts
from
Amazon S3
and perform
other
operations.
For more
information,
see
Authorize
core devices
to interact
with AWS
services (p. 790).
*.s3.amazonaws.com 443 Yes Used for
deployments.
This format
includes the
* character,
because
endpoint
prefixes are
controlled
internally
and might
change at
any time.
808
AWS IoT Greengrass Developer Guide, Version 2
Endpoints for installation with automatic provisioning
Endpoint Port Required Description
data.iot.region.amazonaws.com 443 No Required
if the core
device runs
a version
of the
Greengrass
nucleus (p. 181)
earlier than
v2.4.0 and is
configured
to use a
network
proxy. The
core device
uses this
endpoint
for MQTT
communication
with AWS
IoT Core
when
behind
a proxy.
For more
information,
see
Configure
a network
proxy (p. 167).
Endpoints for installation with automatic
provisioning
Greengrass core devices use the following endpoints and ports when you install the AWS IoT Greengrass
Core software with automatic resource provisioning (p. 69).
Endpoint Port Required Description
iot.region.amazonaws.com 443 Yes Used to
create
AWS IoT
resources
and retrieve
information
about
existing
AWS IoT
resources.
iam.amazonaws.com 443 Yes Used to
create IAM
resources
809
AWS IoT Greengrass Developer Guide, Version 2
Endpoints for AWS-provided components
Endpoint Port Required Description
and retrieve
information
about
existing IAM
resources.
sts.region.amazonaws.com 443 Yes Used to get
the ID of
your AWS
account.
greengrass.region.amazonaws.com 443 No Required if
you use the
--deploy-
dev-tools
argument to
deploy the
Greengrass
CLI
component
to the core
device.
Endpoints for AWS-provided components
Greengrass core devices use additional endpoints depending on which software components they
run. You can find the endpoints that each AWS-provided component requires in the Requirements
section on each component's page in this developer guide. For more information, see AWS-provided
components (p. 175).
Compliance validation for AWS IoT Greengrass
To learn whether AWS IoT Greengrass or other AWS services are in scope of specific compliance
programs, see AWS Services in Scope by Compliance Program. For general information, see AWS
Compliance Programs.
You can download third-party audit reports using AWS Artifact. For more information, see Downloading
Reports in AWS Artifact.
Your compliance responsibility when using AWS services is determined by the sensitivity of your data,
your company's compliance objectives, and applicable laws and regulations. AWS provides the following
resources to help with compliance:
• Security and Compliance Quick Start Guides – These deployment guides discuss architectural
considerations and provide steps for deploying baseline environments on AWS that are security and
compliance focused.
• Architecting for HIPAA Security and Compliance Whitepaper – This whitepaper describes how
companies can use AWS to create HIPAA-compliant applications.
Note
Not all services are compliant with HIPAA.
• AWS Compliance Resources – This collection of workbooks and guides might apply to your industry
and location.
810
AWS IoT Greengrass Developer Guide, Version 2
Resilience
• Evaluating Resources with Rules in the AWS Config Developer Guide – The AWS Config service assesses
how well your resource configurations comply with internal practices, industry guidelines, and
regulations.
• AWS Security Hub – This AWS service provides a comprehensive view of your security state within AWS
that helps you check your compliance with security industry standards and best practices.
• AWS Audit Manager – This AWS service helps you continuously audit your AWS usage to simplify how
you manage risk and compliance with regulations and industry standards.
Resilience in AWS IoT Greengrass
The AWS global infrastructure is built around Amazon Web Services Regions and Availability Zones. Each
AWS Region provides multiple physically separated and isolated Availability Zones, which are connected
with low-latency, high-throughput, and highly redundant networking. With Availability Zones, you can
design and operate applications and databases that automatically fail over between zones without
interruption. Availability Zones are more highly available, fault tolerant, and scalable than traditional
single or multiple data center infrastructures.
For more information, see AWS Global Infrastructure.
In addition to the AWS global infrastructure, AWS IoT Greengrass offers several features to help support
your data resiliency and backup needs.
• If the core loses internet connectivity, Greengrass devices can continue to communicate over the local
network.
• You can configure a Greengrass core device to write logs to the local file system and to CloudWatch
Logs. If the core loses connectivity, local logging can continue, but CloudWatch logs are sent with a
limited number of retries. After the retries are exhausted, the event is dropped. For more information,
see the log manager component (p. 273).
• You can author Greengrass components that read stream manager (p. 682) streams and send the data
to local storage destinations.
Infrastructure security in AWS IoT Greengrass
As a managed service, AWS IoT Greengrass is protected by the AWS global network security procedures
that are described in the Amazon Web Services: Overview of Security Processes whitepaper.
You use AWS published API calls to access AWS IoT Greengrass through the network. Clients must
support Transport Layer Security (TLS) 1.0 or later. We recommend TLS 1.2 or later. Clients must also
support cipher suites with perfect forward secrecy (PFS), such as Ephemeral Diffie-Hellman (DHE) or
Elliptic Curve Ephemeral Diffie-Hellman (ECDHE). Most modern systems such as Java 7 and later support
these modes.
Requests must be signed by using an access key ID and a secret access key that is associated with an
IAM principal. Or you can use the AWS Security Token Service (AWS STS) to generate temporary security
credentials to sign requests.
In an AWS IoT Greengrass environment, devices use X.509 certificates and cryptographic keys to connect
and authenticate to the AWS Cloud. For more information, see the section called “Device authentication
and authorization” (p. 773).
811
AWS IoT Greengrass Developer Guide, Version 2
Configuration and vulnerability analysis
Configuration and vulnerability analysis in AWS IoT
Greengrass
IoT environments can consist of large numbers of devices that have diverse capabilities, are long-lived,
and are geographically distributed. These characteristics make device setup complex and error-prone.
And because devices are often constrained in computational power, memory, and storage capabilities,
this limits the use of encryption and other forms of security on the devices themselves. Also, devices
often use software with known vulnerabilities. These factors make IoT devices an attractive target for
hackers and make it difficult to secure them on an ongoing basis.
AWS IoT Device Defender addresses these challenges by providing tools to identify security issues and
deviations from best practices. You can use AWS IoT Device Defender to analyze, audit, and monitor
connected devices to detect abnormal behavior, and mitigate security risks. AWS IoT Device Defender can
audit devices to ensure they adhere to security best practices and detect abnormal behavior on devices.
This makes it possible to enforce consistent security policies across your devices and respond quickly
when devices are compromised. IFor more information, see the following topics:
• The Device Defender component (p. 230)
• AWS IoT Device Defender in the AWS IoT Core Developer Guide.
In AWS IoT Greengrass environments, you should be aware of the following considerations:
• It's your reponsibility to secure your physical devices, the file system on your devices, and the local
network.
• AWS IoT Greengrass doesn't enforce network isolation for user-defined Greengrass components,
whether or not they run in a Greengrass container. Therefore, it's possible for Greengrass components
to communicate with any other process running in the system or outside over network.
Code integrity in AWS IoT Greengrass V2
AWS IoT Greengrass deploys software components from the AWS Cloud to devices that run the AWS IoT
Greengrass Core software. These software components include AWS-provided components (p. 175) and
custom components (p. 442) that you upload to your AWS account. Every component is composed of a
recipe. The recipe defines the component's metadata, and any number of artifacts, which are component
binaries, such as compiled code and static resources. Component artifacts are stored in Amazon S3.
As you develop and deploy Greengrass components, you follow these basic steps that work with
component artifacts in your AWS account and on your devices:
1. Create and upload artifacts to S3 buckets.
2. Create a component from a recipe and artifacts in the AWS IoT Greengrass service, which calculates a
cryptographic hash of each artifact.
3. Deploy a component to Greengrass core devices, which download and verify the integrity of each
artifact.
AWS is responsible for maintaining the integrity of artifacts after you upload artifacts to S3 buckets,
including when you deploy components to Greengrass core devices. You are responsible for securing
software artifacts before you upload the artifacts to S3 buckets. You are also responsible for securing
access to resources in your AWS account, including the S3 buckets where you upload component
artifacts.
812
AWS IoT Greengrass Developer Guide, Version 2
VPC endpoints (AWS PrivateLink)
Note
Amazon S3 provides a feature called S3 Object Lock that you can use to protect against changes
to component artifacts in S3 buckets your AWS account. You can use S3 Object Lock to prevent
component artifacts from being deleted or overwritten. For more information, see Using S3
Object Lock in the Amazon Simple Storage Service User Guide.
When AWS publishes a public component, and when you upload a custom component, AWS IoT
Greengrass calculates a cryptographic digest for each component artifact. AWS IoT Greengrass updates
the component recipe to include each artifact's digest and the hash algorithm used to calculate that
digest. This digest guarantees the integrity of the artifact, because if the artifact changes in the AWS
Cloud or during download, its file digest won't match the digest that AWS IoT Greengrass stores in the
component recipe. For more information, see Artifacts in the component recipe reference (p. 481).
When you deploy a component to a core device, the AWS IoT Greengrass Core software downloads
the component recipe and each component artifact that the recipe defines. The AWS IoT Greengrass
Core software calculates the digest of each downloaded artifact file and compares it with that artifact's
digest in the recipe. If the digests don't match, the deployment fails, and the AWS IoT Greengrass
Core software deletes the downloaded artifacts from the device's file system. For more information
about how connections between core devices and AWS IoT Greengrass are secured, see Encryption in
transit (p. 771).
You are responsible for securing component artifact files on your core devices' file systems. The AWS
IoT Greengrass Core software saves artifacts to the packages folder in the Greengrass root folder. You
can use AWS IoT Device Defender to analyze, audit, and monitor core devices. For more information, see
Configuration and vulnerability analysis in AWS IoT Greengrass (p. 812).
AWS IoT Greengrass and interface VPC endpoints
(AWS PrivateLink)
You can establish a private connection between your VPC and the AWS IoT Greengrass control plane by
creating an interface VPC endpoint. You can use this endpoint to manage components, deployments, and
core devices in the AWS IoT Greengrass service. Interface endpoints are powered by AWS PrivateLink, a
technology that enables you to access AWS IoT Greengrass APIs privately without an internet gateway,
NAT device, VPN connection, or AWS Direct Connect connection. Instances in your VPC don't need public
IP addresses to communicate with AWS IoT Greengrass APIs. Traffic between your VPC and AWS IoT
Greengrass does not leave the Amazon network.
Note
Currently, you can't configure Greengrass core devices to operate completely within your VPC.
Each interface endpoint is represented by one or more Elastic Network Interfaces in your subnets.
For more information, see Interface VPC endpoints (AWS PrivateLink) in the Amazon VPC User Guide.
Topics
• Considerations for AWS IoT Greengrass VPC endpoints (p. 814)
• Create an interface VPC endpoint for AWS IoT Greengrass control plane operations (p. 814)
• Creating a VPC endpoint policy for AWS IoT Greengrass (p. 814)
813
AWS IoT Greengrass Developer Guide, Version 2
Considerations for AWS IoT Greengrass VPC endpoints
Considerations for AWS IoT Greengrass VPC
endpoints
Before you set up an interface VPC endpoint for AWS IoT Greengrass, review Interface endpoint
properties and limitations in the Amazon VPC User Guide. Additionally, be aware of the following
considerations:
• AWS IoT Greengrass supports making calls to all of its control plane API actions from your VPC.
The control plane includes operations such as CreateDeployment and ListEffectiveDeployments.
The control plane does not include operations such as ResolveComponentCandidates (p. 774) and
Discover (p. 664), which are data plane operations.
• VPC endpoints for AWS IoT Greengrass are currently not supported in AWS China Regions.
Create an interface VPC endpoint for AWS IoT
Greengrass control plane operations
You can create a VPC endpoint for the AWS IoT Greengrass control plane using either the Amazon VPC
console or the AWS Command Line Interface (AWS CLI). For more information, see Creating an interface
endpoint in the Amazon VPC User Guide.
Create a VPC endpoint for AWS IoT Greengrass using the following service name:
• com.amazonaws.region.greengrass
If you enable private DNS for the endpoint, you can make API requests to AWS IoT Greengrass using its
default DNS name for the Region, for example, greengrass.us-east-1.amazonaws.com. Private
DNS is enabled by default.
For more information, see Accessing a service through an interface endpoint in the Amazon VPC User
Guide.
Creating a VPC endpoint policy for AWS IoT
Greengrass
You can attach an endpoint policy to your VPC endpoint that controls access to AWS IoT Greengrass
control plane operations. The policy specifies the following information:
• The principal that can perform actions.
• The actions that the principal can perform.
• The resources that the principal can perform actions on.
For more information, see Controlling access to services with VPC endpoints in the Amazon VPC User
Guide.
Example Example: VPC endpoint policy for AWS IoT Greengrass actions
The following is an example of an endpoint policy for AWS IoT Greengrass. When attached to an
endpoint, this policy grants access to the listed AWS IoT Greengrass actions for all principals on all
resources.
814
AWS IoT Greengrass Developer Guide, Version 2
Security best practices
"Statement": [
{
"Principal": "*",
"Effect": "Allow",
"Action": [
"greengrass:CreateDeployment",
"greengrass:ListEffectiveDeployments"
],
"Resource": "*"
}
]
}
Security best practices for AWS IoT Greengrass
This topic contains security best practices for AWS IoT Greengrass.
Grant minimum possible permissions
Follow the principle of least privilege by using the minimum set of permissions in IAM roles. Limit the use
of the * wildcard for the Action and Resource properties in your IAM policies. Instead, declare a finite
set of actions and resources when possible. For more information about least privilege and other policy
best practices, see the section called “Policy best practices” (p. 789).
The least privilege best practice also applies to AWS IoT policies you attach to your Greengrass core.
Don't hardcode credentials in Greengrass
components
Don't hardcode credentials in your user-defined Greengrass components. To better protect your
credentials:
• To interact with AWS services, define permissions for specific actions and resources in the Greengrass
core device service role (p. 790).
• Use the secret manager component (p. 374) to store your credentials. Or, if the function uses the AWS
SDK, use credentials from the default credential provider chain.
Don't log sensitive information
You should prevent the logging of credentials and other personally identifiable information (PII). We
recommend that you implement the following safeguards even though access to local logs on a core
device requires root privileges and access to CloudWatch Logs requires IAM permissions.
• Don't use sensitive information in MQTT topic paths.
• Don't use sensitive information in device (thing) names, types, and attributes in the AWS IoT Core
registry.
• Don't log sensitive information in your user-defined Greengrass components or Lambda functions.
• Don't use sensitive information in the names and IDs of Greengrass resources:
• Core devices
• Components
• Deployments
815
AWS IoT Greengrass Developer Guide, Version 2
Keep your device clock in sync
• Loggers
Keep your device clock in sync
It's important to have an accurate time on your device. X.509 certificates have an expiry date and time.
The clock on your device is used to verify that a server certificate is still valid. Device clocks can drift over
time or batteries can get discharged.
For more information, see the Keep your device's clock in sync best practice in the AWS IoT Core
Developer Guide.
See also
• Security best practices in AWS IoT Core in the AWS IoT Developer Guide
• Ten security golden rules for IoT solutions on the Internet of Things on AWS Official Blog
816
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass qualification suite
Using AWS IoT Device Tester for AWS
IoT Greengrass V2
AWS IoT Device Tester (IDT) is a downloadable testing framework that lets you validate IoT devices. You
can use IDT for AWS IoT Greengrass to run the AWS IoT Greengrass qualification suite, and create and
run custom test suites for your devices.
IDT for AWS IoT Greengrass runs on your host computer (Windows, macOS, or Linux) connected to the
device to be tested. It runs tests and aggregates results. It also provides a command line interface to
manage the testing process.
AWS IoT Greengrass qualification suite
Use AWS IoT Device Tester for AWS IoT Greengrass V2 to verify that the AWS IoT Greengrass Core
software runs on your hardware and can communicate with the AWS Cloud. It also performs end-to-end
tests with AWS IoT Core. For example, it verifies that your device can deploy components and upgrade
them.
If you want to add your hardware to the AWS Partner Device Catalog, run the AWS IoT Greengrass
qualification suite to generate test reports that you can submit to AWS IoT. For more information, see
AWS Device Qualification Program.
IDT for AWS IoT Greengrass V2 organizes tests using the concepts of test suites and test groups.
• A test suite is the set of test groups used to verify that a device works with particular versions of AWS
IoT Greengrass.
• A test group is the set of individual tests related to a particular feature, such as component
deployments.
For more information, see Use IDT to run the AWS IoT Greengrass qualification suite (p. 820).
817
AWS IoT Greengrass Developer Guide, Version 2
Custom test suites
Custom test suites
Starting in IDT v4.0.1, IDT for AWS IoT Greengrass V2 combines a standardized configuration setup and
result format with a test suite environment that enables you to develop custom test suites for your
devices and device software. You can add custom tests for your own internal validation or provide them
to your customers for device verification.
How a test writer configures a custom test suite determines the settings configurations that are
required to run custom test suites. For more information, see Use IDT to develop and run your own test
suites (p. 847).
Supported versions of AWS IoT Device Tester for
AWS IoT Greengrass V2
This topic lists supported versions of IDT for AWS IoT Greengrass V2. As a best practice, we recommend
that you use the latest version of IDT for AWS IoT Greengrass V2 that supports your target version of
AWS IoT Greengrass V2. New releases of AWS IoT Greengrass might require you to download a new
version of IDT for AWS IoT Greengrass V2. You receive a notification when you start a test run if IDT for
AWS IoT Greengrass V2 is not compatible with the version of AWS IoT Greengrass you are using.
By downloading the software, you agree to the AWS IoT Device Tester License Agreement.
Note
IDT does not support being run by multiple users from a shared location, such as an NFS
directory or a Windows network shared folder. We recommend that you extract the IDT package
to a local drive and run the IDT binary on your local workstation.
Latest IDT version for AWS IoT Greengrass V2
You can use this version of IDT for AWS IoT Greengrass V2 with the AWS IoT Greengrass version listed
here.
IDT v4.4.1 for AWS IoT Greengrass
Supported AWS IoT Greengrass versions:
• Greengrass nucleus (p. 181) v2.5.2
IDT software downloads:
• IDT v4.4.1 with test suite GGV2Q_2.2.0 for Linux
• IDT v4.4.1 with test suite GGV2Q_2.2.0 for macOS
• IDT v4.4.1 with test suite GGV2Q_2.2.0 for Windows
Release notes:
• Enables you to validate and qualify devices running AWS IoT Greengrass Core software v2.5.2.
• Add supports for using a user-defined IAM role as the token exchange role that the device
under test assumes to interact with AWS resources.
You can specify the IAM role in the userdata.json file (p. 840). If you specify a custom
role, IDT uses that role instead of creating the default token exchange role during the test run.
• Additional minor bug fixes.
Test suite version:
GGV2Q_2.2.0
• Released 2021.12.06
818
AWS IoT Greengrass Developer Guide, Version 2
Earlier IDT versions for AWS IoT Greengrass
Earlier IDT versions for AWS IoT Greengrass
The following earlier versions of IDT for AWS IoT Greengrass V2 are also supported.
IDT v4.4.0 for AWS IoT Greengrass
Supported AWS IoT Greengrass versions:
• Greengrass nucleus (p. 181) v2.5.0
IDT software downloads:
• IDT v4.4.0 with test suite GGV2Q_2.1.0 for Linux
• IDT v4.4.0 with test suite GGV2Q_2.1.0 for macOS
• IDT v4.4.0 with test suite GGV2Q_2.1.0 for Windows
Release notes:
• Enables you to validate and qualify devices running AWS IoT Greengrass Core software v2.5.0.
• Adds support for validating and qualifying devices running AWS IoT Greengrass Core software
on Windows.
• Supports the use of public key validation for secure shell (SSH) device connections.
• Improves the IDT permissions IAM policy with security best practices.
• Additional minor bug fixes.
Test suite version:
GGV2Q_2.1.0
• Released 2021.11.19
Unsupported versions of AWS IoT Device Tester for
AWS IoT Greengrass V2
This topic lists unsupported versions of IDT for AWS IoT Greengrass V2. Unsupported versions do not
receive bug fixes or updates. For more information, see the section called “Support policy for AWS IoT
Device Tester for AWS IoT Greengrass” (p. 910).
IDT v4.2.0 for AWS IoT Greengrass
Release notes:
• Includes support for qualification of the following features on devices running AWS IoT
Greengrass Core software v2.2.0 and later versions:
• Docker—Validates that devices can download a Docker container image from Amazon
Elastic Container Registry (Amazon ECR).
• Machine learning—Validates that devices can perform machine learning (ML) inference
using the Deep Learning Runtime or TensorFlow Lite ML frameworks.
• Stream manager—Validates that devices can download, install, and run the AWS IoT
Greengrass stream manager.
• Enables you to validate and qualify devices running AWS IoT Greengrass Core software v2.4.0,
v2.3.0, v2.2.0, and v2.1.0.
• Groups the test logs for each test case in a separate <test-case-id> folder within the
<device-tester-extract-location>/results/<execution-id>/logs/<test-
group-id> directory.
• Additional minor bug fixes.
Test suite version:
GGV2Q_2.0.1
• Released 2021.08.31
819
AWS IoT Greengrass Developer Guide, Version 2
Use IDT to run the AWS IoT Greengrass qualification suite
IDT v4.1.0 for AWS IoT Greengrass
Release notes:
• Enables you to validate and qualify devices running AWS IoT Greengrass Core software v2.3.0,
v2.2.0, v2.1.0, and v2.0.5.
• Improves the userdata.json configuration by removing the requirement to specify the
GreengrassNucleusVersion and GreengrassCLIVersion properties.
• Includes support for Lambda and MQTT feature qualification for AWS IoT Greengrass Core
software v2.1.0 and later versions. You can now use IDT for AWS IoT Greengrass V2 to validate
that your core device can run Lambda functions and that the device can publish and subscribe
to AWS IoT Core MQTT topics.
• Improves logging capabilities.
• Additional minor bug fixes.
Test suite version:
GGV2Q_1.1.1
• Released 2021.06.18
IDT v4.0.2 for AWS IoT Greengrass
Release notes:
• Enables you to validate and qualify devices running AWS IoT Greengrass Core software v2.1.0.
• Adds support for Lambda and MQTT feature qualification for AWS IoT Greengrass Core
software v2.1.0 and later versions. You can now use IDT for AWS IoT Greengrass V2 to validate
that your core device can run Lambda functions and that the device can publish and subscribe
to AWS IoT Core MQTT topics.
• Improves logging capabilities.
• Additional minor bug fixes.
Test suite version:
GGV2Q_1.1.1
• Released 2021.05.05
IDT v4.0.1 for AWS IoT Greengrass
Release notes:
• Enables you to validate and qualify devices running AWS IoT Greengrass Version 2 software.
• Enables you to develop and run your custom test suites using AWS IoT Device Tester for
AWS IoT Greengrass. For more information, see Use IDT to develop and run your own test
suites (p. 847).
• Provides code signed IDT applications for macOS and Windows. On macOS, you might
need to grant a security exception for IDT. For more information, see Security exception on
macOS (p. 908).
Test suite version:
GGV2Q_1.0.0
• Released 2020.12.22
• The test suite runs only required tests for qualification, unless you set the corresponding
value in the features array to yes.
Use IDT to run the AWS IoT Greengrass
qualification suite
You can use AWS IoT Device Tester for AWS IoT Greengrass V2 to verify that the AWS IoT Greengrass
Core software runs on your hardware and can communicate with the AWS Cloud. It also performs end-
820
AWS IoT Greengrass Developer Guide, Version 2
Test suite versions
to-end tests with AWS IoT Core. For example, it verifies that your device can deploy components and
upgrade them.
In addition to testing devices, IDT for AWS IoT Greengrass V2 creates resources (for example, AWS IoT
things, groups, and so on) in your AWS account to facilitate the qualification process.
To create these resources, IDT for AWS IoT Greengrass V2 uses the AWS credentials configured in the
config.json file to make API calls on your behalf. These resources are provisioned at various times
during a test.
When you use IDT for AWS IoT Greengrass V2 to run the AWS IoT Greengrass qualification suite, it
performs the following steps:
1. Loads and validates your device and credentials configuration.
2. Performs selected tests with the required local and cloud resources.
3. Cleans up local and cloud resources.
4. Generates tests reports that indicate if your board passed the tests required for qualification.
Test suite versions
IDT for AWS IoT Greengrass V2 organizes tests into test suites and test groups.
• A test suite is the set of test groups used to verify that a device works with particular versions of AWS
IoT Greengrass.
• A test group is the set of individual tests related to a particular feature, such as component
deployments.
Test suites are versioned using a major.minor.patch format, for example GGV2Q_1.0.0. When you
download IDT, the package includes the latest Greengrass qualification suite version.
Important
IDT supports the four latest major.minor versions of the Greengrass qualification suite
versions to generate qualification reports that you can submit to AWS Partner Network to
include your devices in the AWS Partner Device Catalog. Tests from unsupported test suite
versions are not valid for device qualification. IDT doesn't print qualification reports for
unsupported versions. For more information, see the section called “Support policy for AWS IoT
Device Tester for AWS IoT Greengrass” (p. 910).
You can run list-supported-products to list the versions of AWS IoT Greengrass and test
suites that are supported by your current version of IDT.
Test group descriptions
IDT v4.4.0
Required Test Groups for Core Qualification
These test groups are required to qualify your AWS IoT Greengrass V2 device for the AWS
Partner Device Catalog.
Core Dependencies
Validates that the device meets all software and hardware requirements for the AWS IoT
Greengrass Core software. This test group includes the following test case:
Java Version
Checks that the required Java version is installed on the device under test. AWS IoT
Greengrass requires Java 8 or later.
821
AWS IoT Greengrass Developer Guide, Version 2
Test group descriptions
PreTest Validation
Checks that the device meets the software requirements to run tests.
• For Linux-based devices, this test checks if the device can run the following Linux
commands:
chmod, cp, echo, grep, kill, ln, mkinfo, ps, rm, sh, uname
• For Windows-based devices, this test checks if the device has the following Microsoft
software installed:
Powershell v5.1 or later, .NET v4.6.1 or later, Visual C++ 2017 or later, PsExec utility
Version Checker
Checks that the version of AWS IoT Greengrass provided is compatible with the AWS IoT
Device Tester version you are using.
Component
Validates that the device can deploy components and upgrade them. This test group
includes the following tests:
Cloud Component
Validates device capability for cloud components.
Local Component
Validates device capability for local components.
Lambda
This test is not applicable for Windows-based devices.
Validates that the device can deploy Lambda function components that use the Java
runtime, and that the Lambda functions can use AWS IoT Core MQTT topics as event
sources for work messages.
MQTT
Validates that the device can subscribe and publish to AWS IoT Core MQTT topics.
Optional Test Groups
Note
These test groups are optional, and used only for qualifying Linux-based Greengrass
core devices. If you choose to qualify for optional tests, your device is listed with
additional capabilities in the AWS Partner Device Catalog.
Docker dependencies
Validates that the device meets all required technical dependencies to use the AWS-
provided Docker application manager (aws.greengrass.DockerApplicationManager)
component.
Docker Application Manager Qualification
Validates that the device can download a Docker container image from Amazon Elastic
Container Registry (Amazon ECR).
Machine Learning Dependencies
Validates that the device meets all of the required technical dependencies to use the AWS-
provided machine learning (ML) components.
Machine Learning Inference Tests
Validates that the device can perform ML inference using the Deep Learning Runtime and
TensorFlow Lite ML frameworks.
822
AWS IoT Greengrass Developer Guide, Version 2
Test group descriptions
Stream Manager Dependencies
Validates that the device can download, install, and run the AWS IoT Greengrass stream
manager (p. 682).
IDT v4.2.0
Required Test Groups for Core Qualification
These test groups are required to qualify your AWS IoT Greengrass V2 device for the AWS
Partner Device Catalog.
Core Dependencies
Validates that the device meets all software and hardware requirements for the AWS IoT
Greengrass Core software. This test group includes the following test case:
Java Version
Checks that the required Java version is installed on the device under test. AWS IoT
Greengrass requires Java 8 or later.
PreTest Validation
Checks that the device can run the following Linux commands:
chmod, cp, echo, grep, kill, ln, mkinfo, ps, rm, sh, uname
Version Checker
Checks that the version of AWS IoT Greengrass provided is compatible with the AWS IoT
Device Tester version you are using.
Component
Validates that the device can deploy components and upgrade them. This test group
includes the following tests:
Cloud Component
Validates device capability for cloud components.
Local Component
Validates device capability for local components.
Lambda
Validates that the device can deploy Lambda function components that use the Java
runtime, and that the Lambda functions can use AWS IoT Core MQTT topics as event
sources for work messages.
MQTT
Validates that the device can subscribe and publish to AWS IoT Core MQTT topics.
Optional Test Groups
These test groups are optional. If you choose to qualify for optional tests, your device is listed
with additional capabilities in the AWS Partner Device Catalog.
Docker dependencies
Validates that the device meets all required technical dependencies to use the AWS-
provided Docker application manager (aws.greengrass.DockerApplicationManager)
component.
823
AWS IoT Greengrass Developer Guide, Version 2
Prerequisites
Docker Application Manager Qualification
Validates that the device can download a Docker container image from Amazon Elastic
Container Registry (Amazon ECR).
Machine Learning Dependencies
Validates that the device meets all of the required technical dependencies to use the AWS-
provided machine learning (ML) components.
Machine Learning Inference Tests
Validates that the device can perform ML inference using the Deep Learning Runtime and
TensorFlow Lite ML frameworks.
Stream Manager Dependencies
Validates that the device can download, install, and run the AWS IoT Greengrass stream
manager (p. 682).
Prerequisites for running the AWS IoT Greengrass
qualification suite
This section describes the prerequisites for using AWS IoT Device Tester (IDT) for AWS IoT Greengrass.
Download the latest version of AWS IoT Device Tester for AWS
IoT Greengrass
Download the latest version (p. 818) of IDT and extract the software into a location (<device-
tester-extract-location>) on your file system where you have read/write permissions.
Note
IDT does not support being run by multiple users from a shared location, such as an NFS
directory or a Windows network shared folder. We recommend that you extract the IDT package
to a local drive and run the IDT binary on your local workstation.
Windows has a path length limitation of 260 characters. If you are using Windows, extract IDT to
a root directory like C:\ or D:\ to keep your paths under the 260 character limit.
Download the AWS IoT Greengrass software
IDT for AWS IoT Greengrass V2 tests your device for compatibility with a specific version of AWS IoT
Greengrass. Run the following command to download the AWS IoT Greengrass Core software to a file
named aws.greengrass.nucleus.zip. Replace version with a supported nucleus component
version (p. 818) for your IDT version.
Linux or Unix
curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-version.zip >
aws.greengrass.nucleus.zip
Windows Command Prompt (CMD)
curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-version.zip >
aws.greengrass.nucleus.zip
824
AWS IoT Greengrass Developer Guide, Version 2
Prerequisites
PowerShell
iwr -Uri https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-version.zip -OutFile
aws.greengrass.nucleus.zip
Place the downloaded aws.greengrass.nucleus.zip file in the <device-tester-extract-
location>/products/ folder.
Note
Do not place multiple files in this directory for the same operating system and architecture.
Create and configure an AWS account
Before you can use AWS IoT Device Tester for AWS IoT Greengrass V2, you must perform the following
steps:
1. Set up an AWS account. (p. 825) If you already have an AWS account, skip to step 2.
2. Configure permissions for IDT. (p. 826)
These account permissions allow IDT to access AWS services and create AWS resources, such as AWS IoT
things and AWS IoT Greengrass components, on your behalf.
To create these resources, IDT for AWS IoT Greengrass V2 uses the AWS credentials configured in the
config.json file to make API calls on your behalf. These resources are provisioned at various times
during a test.
Note
Although most tests qualify for AWS Free Tier, you must provide a credit card when you sign up
for an AWS account. For more information, see Why do I need a payment method if my account
is covered by the Free Tier?.
Step 1: Set up an AWS account
In this step, create and configure an AWS account. If you already have an AWS account, skip to the
section called “Step 2: Configure permissions for IDT” (p. 826).
If you do not have an AWS account, complete the following steps to create one.
To sign up for an AWS account
1. Open https://portal.aws.amazon.com/billing/signup.
2. Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call and entering a verification code on the
phone keypad.
To create an administrator user for yourself and add the user to an administrators group
(console)
1. Sign in to the IAM console as the account owner by choosing Root user and entering your AWS
account email address. On the next page, enter your password.
Note
We strongly recommend that you adhere to the best practice of using the Administrator
IAM user that follows and securely lock away the root user credentials. Sign in as the root
user only to perform a few account and service management tasks.
825
AWS IoT Greengrass Developer Guide, Version 2
Prerequisites
2. In the navigation pane, choose Users and then choose Add user.
3. For User name, enter Administrator.
4. Select the check box next to AWS Management Console access. Then select Custom password, and
then enter your new password in the text box.
5. (Optional) By default, AWS requires the new user to create a new password when first signing in. You
can clear the check box next to User must create a new password at next sign-in to allow the new
user to reset their password after they sign in.
6. Choose Next: Permissions.
7. Under Set permissions, choose Add user to group.
8. Choose Create group.
9. In the Create group dialog box, for Group name enter Administrators.
10. Choose Filter policies, and then select AWS managed - job function to filter the table contents.
11. In the policy list, select the check box for AdministratorAccess. Then choose Create group.
Note
You must activate IAM user and role access to Billing before you can use the
AdministratorAccess permissions to access the AWS Billing and Cost Management
console. To do this, follow the instructions in step 1 of the tutorial about delegating access
to the billing console.
12. Back in the list of groups, select the check box for your new group. Choose Refresh if necessary to
see the group in the list.
13. Choose Next: Tags.
14. (Optional) Add metadata to the user by attaching tags as key-value pairs. For more information
about using tags in IAM, see Tagging IAM entities in the IAM User Guide.
15. Choose Next: Review to see the list of group memberships to be added to the new user. When you
are ready to proceed, choose Create user.
You can use this same process to create more groups and users and to give your users access to your AWS
account resources. To learn about using policies that restrict user permissions to specific AWS resources,
see Access management and Example policies.
Step 2: Configure permissions for IDT
In this step, configure the permissions that IDT for AWS IoT Greengrass V2 uses to run tests and collect
IDT usage data. You can use the AWS Management Console (p. 826) or AWS Command Line Interface
(AWS CLI) (p. 829) to create an IAM policy and a test user for IDT, and then attach policies to the user. If
you already created a test user for IDT, skip to Configure your device to run IDT tests (p. 832).
To configure permissions for IDT (console)
1. Sign in to the IAM console.
2. Create a customer managed policy that grants permissions to create roles with specific permissions.
a. In the navigation pane, choose Policies, and then choose Create policy.
b. On the JSON tab, replace the placeholder content with the following policy.
{
"Version":"2012-10-17",
"Statement":[
{
"Sid":"passRoleForResources",
"Effect":"Allow",
"Action":"iam:PassRole",
"Resource":"arn:aws:iam::*:role/idt-*",
"Condition":{
826
AWS IoT Greengrass Developer Guide, Version 2
Prerequisites
"StringEquals":{
"iam:PassedToService":[
"iot.amazonaws.com",
"lambda.amazonaws.com",
"greengrass.amazonaws.com"
]
}
}
},
{
"Sid":"lambdaResources",
"Effect":"Allow",
"Action":[
"lambda:CreateFunction",
"lambda:PublishVersion",
"lambda:DeleteFunction",
"lambda:GetFunction"
],
"Resource":[
"arn:aws:lambda:*:*:function:idt-*"
]
},
{
"Sid":"iotResources",
"Effect":"Allow",
"Action":[
"iot:CreateThing",
"iot:DeleteThing",
"iot:DescribeThing",
"iot:CreateThingGroup",
"iot:DeleteThingGroup",
"iot:DescribeThingGroup",
"iot:AddThingToThingGroup",
"iot:RemoveThingFromThingGroup",
"iot:AttachThingPrincipal",
"iot:DetachThingPrincipal",
"iot:UpdateCertificate",
"iot:DeleteCertificate",
"iot:CreatePolicy",
"iot:AttachPolicy",
"iot:DetachPolicy",
"iot:DeletePolicy",
"iot:GetPolicy",
"iot:Publish",
"iot:TagResource",
"iot:ListThingPrincipals",
"iot:ListAttachedPolicies"
],
"Resource":[
"arn:aws:iot:*:*:thing/idt-*",
"arn:aws:iot:*:*:thinggroup/idt-*",
"arn:aws:iot:*:*:policy/idt-*",
"arn:aws:iot:*:*:cert/*",
"arn:aws:iot:*:*:topic/idt-*"
]
},
{
"Sid":"s3Resources",
"Effect":"Allow",
"Action":[
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObjectVersion",
"s3:DeleteObject",
"s3:CreateBucket",
"s3:ListBucket",
827
AWS IoT Greengrass Developer Guide, Version 2
Prerequisites
"s3:ListBucketVersions",
"s3:DeleteBucket",
"s3:PutObjectTagging",
"s3:PutBucketTagging"
],
"Resource":"arn:aws:s3::*:idt-*"
},
{
"Sid":"roleAliasResources",
"Effect":"Allow",
"Action":[
"iot:CreateRoleAlias",
"iot:DescribeRoleAlias",
"iot:DeleteRoleAlias",
"iot:TagResource",
"iam:GetRole"
],
"Resource":[
"arn:aws:iot:*:*:rolealias/idt-*",
"arn:aws:iam::*:role/idt-*"
]
},
{
"Sid":"idtExecuteAndCollectMetrics",
"Effect":"Allow",
"Action":[
"iot-device-tester:SendMetrics",
"iot-device-tester:SupportedVersion",
"iot-device-tester:LatestIdt",
"iot-device-tester:CheckVersion",
"iot-device-tester:DownloadTestSuite"
],
"Resource":"*"
},
{
"Sid":"genericResources",
"Effect":"Allow",
"Action":[
"greengrass:*",
"iot:GetThingShadow",
"iot:UpdateThingShadow",
"iot:ListThings",
"iot:DescribeEndpoint",
"iot:CreateKeysAndCertificate"
],
"Resource":"*"
},
{
"Sid":"iamResourcesUpdate",
"Effect":"Allow",
"Action":[
"iam:CreateRole",
"iam:DeleteRole",
"iam:CreatePolicy",
"iam:DeletePolicy",
"iam:AttachRolePolicy",
"iam:DetachRolePolicy",
"iam:TagRole",
"iam:TagPolicy",
"iam:GetPolicy",
"iam:ListAttachedRolePolicies",
"iam:ListEntitiesForPolicy"
],
"Resource":[
"arn:aws:iam::*:role/idt-*",
"arn:aws:iam::*:policy/idt-*"
828
AWS IoT Greengrass Developer Guide, Version 2
Prerequisites
]
}
]
}
Note
If you want to use a custom IAM role as the token exchange role (p. 841) for your
device under test, make sure you update the roleAliasResources statement and
the passRoleForResources statement in your policy to allow your custom IAM role
resource.
c. Choose Review policy.
d. For Name, enter IDTGreengrassIAMPermissions. Under Summary, review the permissions
granted by your policy.
e. Choose Create policy.
3. Create an IAM user and attach the permissions required by IDT for AWS IoT Greengrass.
a. Create an IAM user. Follow steps 1 through 5 in Creating IAM users (console) in the IAM User
Guide.
b. Attach the permissions to your IAM user:
i. On the Set permissions page, choose Attach existing policies to user directly.
ii. Search for the IDTGreengrassIAMPermissions policy that you created in the previous step.
Select the check box.
c. Choose Next: Tags.
d. Choose Next: Review to view a summary of your choices.
e. Choose Create user.
f. To view the user's access keys (access key IDs and secret access keys), choose Show next to the
password and access key. To save the access keys, choose Download.csv and save the file to a
secure location. You use this information later to configure your AWS credentials file.
4. Next step: Configure your physical device (p. 832).
To configure permissions for IDT (AWS CLI)
1. On your computer, install and configure the AWS CLI if it's not already installed. Follow the steps in
Installing the AWS CLI in the AWS Command Line Interface User Guide.
Note
The AWS CLI is an open source tool that you can use to interact with AWS services from
your command-line shell.
2. Create a customer managed policy that grants permissions to manage IDT and AWS IoT Greengrass
roles.
a. Open a text editor and save the following policy contents in a JSON file.
{
"Version":"2012-10-17",
"Statement":[
{
"Sid":"passRoleForResources",
"Effect":"Allow",
"Action":"iam:PassRole",
"Resource":"arn:aws:iam::*:role/idt-*",
"Condition":{
"StringEquals":{
"iam:PassedToService":[
"iot.amazonaws.com",
829
AWS IoT Greengrass Developer Guide, Version 2
Prerequisites
"lambda.amazonaws.com",
"greengrass.amazonaws.com"
]
}
}
},
{
"Sid":"lambdaResources",
"Effect":"Allow",
"Action":[
"lambda:CreateFunction",
"lambda:PublishVersion",
"lambda:DeleteFunction",
"lambda:GetFunction"
],
"Resource":[
"arn:aws:lambda:*:*:function:idt-*"
]
},
{
"Sid":"iotResources",
"Effect":"Allow",
"Action":[
"iot:CreateThing",
"iot:DeleteThing",
"iot:DescribeThing",
"iot:CreateThingGroup",
"iot:DeleteThingGroup",
"iot:DescribeThingGroup",
"iot:AddThingToThingGroup",
"iot:RemoveThingFromThingGroup",
"iot:AttachThingPrincipal",
"iot:DetachThingPrincipal",
"iot:UpdateCertificate",
"iot:DeleteCertificate",
"iot:CreatePolicy",
"iot:AttachPolicy",
"iot:DetachPolicy",
"iot:DeletePolicy",
"iot:GetPolicy",
"iot:Publish",
"iot:TagResource",
"iot:ListThingPrincipals",
"iot:ListAttachedPolicies"
],
"Resource":[
"arn:aws:iot:*:*:thing/idt-*",
"arn:aws:iot:*:*:thinggroup/idt-*",
"arn:aws:iot:*:*:policy/idt-*",
"arn:aws:iot:*:*:cert/*",
"arn:aws:iot:*:*:topic/idt-*"
]
},
{
"Sid":"s3Resources",
"Effect":"Allow",
"Action":[
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObjectVersion",
"s3:DeleteObject",
"s3:CreateBucket",
"s3:ListBucket",
"s3:ListBucketVersions",
"s3:DeleteBucket",
"s3:PutObjectTagging",
830
AWS IoT Greengrass Developer Guide, Version 2
Prerequisites
"s3:PutBucketTagging"
],
"Resource":"arn:aws:s3::*:idt-*"
},
{
"Sid":"roleAliasResources",
"Effect":"Allow",
"Action":[
"iot:CreateRoleAlias",
"iot:DescribeRoleAlias",
"iot:DeleteRoleAlias",
"iot:TagResource",
"iam:GetRole"
],
"Resource":[
"arn:aws:iot:*:*:rolealias/idt-*",
"arn:aws:iam::*:role/idt-*"
]
},
{
"Sid":"idtExecuteAndCollectMetrics",
"Effect":"Allow",
"Action":[
"iot-device-tester:SendMetrics",
"iot-device-tester:SupportedVersion",
"iot-device-tester:LatestIdt",
"iot-device-tester:CheckVersion",
"iot-device-tester:DownloadTestSuite"
],
"Resource":"*"
},
{
"Sid":"genericResources",
"Effect":"Allow",
"Action":[
"greengrass:*",
"iot:GetThingShadow",
"iot:UpdateThingShadow",
"iot:ListThings",
"iot:DescribeEndpoint",
"iot:CreateKeysAndCertificate"
],
"Resource":"*"
},
{
"Sid":"iamResourcesUpdate",
"Effect":"Allow",
"Action":[
"iam:CreateRole",
"iam:DeleteRole",
"iam:CreatePolicy",
"iam:DeletePolicy",
"iam:AttachRolePolicy",
"iam:DetachRolePolicy",
"iam:TagRole",
"iam:TagPolicy",
"iam:GetPolicy",
"iam:ListAttachedRolePolicies",
"iam:ListEntitiesForPolicy"
],
"Resource":[
"arn:aws:iam::*:role/idt-*",
"arn:aws:iam::*:policy/idt-*"
]
}
]
831
AWS IoT Greengrass Developer Guide, Version 2
Configure your device to run IDT tests
Note
If you want to use a custom IAM role as the token exchange role (p. 841) for your
device under test, make sure you update the roleAliasResources statement and
the passRoleForResources statement in your policy to allow your custom IAM role
resource.
b. Run the following command to create a customer managed policy named
IDTGreengrassIAMPermissions. Replace policy.json with the full path to the JSON file
that you created in the previous step.
aws iam create-policy --policy-name IDTGreengrassIAMPermissions --policy-document
file://policy.json
3. Create an IAM user and attach the permissions required by IDT for AWS IoT Greengrass.
a. Create an IAM user. In this example setup, the user is named IDTGreengrassUser.
aws iam create-user --user-name IDTGreengrassUser
b. Attach the IDTGreengrassIAMPermissions policy you created in step 2 to your IAM user.
Replace <account-id> in the command with the ID of your AWS account.
aws iam attach-user-policy --user-name IDTGreengrassUser --policy-arn
arn:aws:iam::<account-id>:policy/IDTGreengrassIAMPermissions
4. Create a secret access key for the user.
aws iam create-access-key --user-name IDTGreengrassUser
Store the output in a secure location. You use this information later to configure your AWS
credentials file.
5. Next step: Configure your physical device (p. 832).
Configure your device to run IDT tests
To enable IDT to run tests for device qualification, you must configure your host computer to access your
device, and configure user permissions on your device.
Install Java on the host computer
Starting with IDT v4.2.0, the optional qualification tests for AWS IoT Greengrass require Java to run.
You can use Java version 8 or greater. We recommend Amazon Corretto 11 or OpenJDK 11.
Configure your host computer to access your device under test
IDT runs on your host computer and must be able to use SSH to connect to your device. There are two
options to allow IDT to gain SSH access to your devices under test:
1. Follow the instructions here to create an SSH key pair and authorize your key to sign in to your device
under test without specifying a password.
2. Provide a user name and password for each device in the device.json file. For more information,
see Configure device.json (p. 837).
832
AWS IoT Greengrass Developer Guide, Version 2
Configure your device to run IDT tests
You can use any SSL implementation to create an SSH key. The following instructions show you how to
use SSH-KEYGEN or PuTTYgen (for Windows). If you are using another SSL implementation, refer to the
documentation for that implementation.
IDT uses SSH keys to authenticate with your device under test.
To create an SSH key with SSH-KEYGEN
1. Create an SSH key.
You can use the Open SSH ssh-keygen command to create an SSH key pair. If you already have an
SSH key pair on your host computer, it is a best practice to create a SSH key pair specifically for
IDT. This way, after you have completed testing, your host computer can no longer connect to your
device without entering a password. It also allows you to restrict access to the remote device to only
those who need it.
Note
Windows does not have an installed SSH client. For information about installing an SSH
client on Windows, see Download SSH Client Software.
The ssh-keygen command prompts you for a name and path to store the key pair. By default, the
key pair files are named id_rsa (private key) and id_rsa.pub (public key). On macOS and Linux,
the default location of these files is ~/.ssh/. On Windows, the default location is C:\Users
\<user-name>\.ssh.
When prompted, enter a key phrase to protect your SSH key. For more information, see Generate a
New SSH key.
2. Add authorized SSH keys to your device under test.
IDT must use your SSH private key to sign in to your device under test. To authorize your SSH private
key to sign in to your device under test, use the ssh-copy-id command from your host computer.
This command adds your public key into the ~/.ssh/authorized_keys file on your device under
test. For example:
$ ssh-copy-id <remote-ssh-user>@<remote-device-ip>
Where remote-ssh-user is the user name used to sign in to your device under test and remote-
device-ip is the IP address of the device under test to run tests against. For example:
ssh-copy-id pi@192.168.1.5
When prompted, enter the password for the user name you specified in the ssh-copy-id command.
ssh-copy-id assumes the public key is named id_rsa.pub and is stored the default location (on
macOS and Linux, ~/.ssh/ and on Windows, C:\Users\<user-name>\.ssh). If you gave the
public key a different name or stored it in a different location, you must specify the fully qualified
path to your SSH public key using the -i option to ssh-copy-id (for example, ssh-copy-id -i ~/my/
path/myKey.pub). For more information about creating SSH keys and copying public keys, see SSH-
COPY-ID.
To create an SSH key using PuTTYgen (Windows only)
1. Make sure you have the OpenSSH server and client installed on your device under test. For more
information, see OpenSSH.
2. Install PuTTYgen on your device under test.
3. Open PuTTYgen.
4. Choose Generate and move your mouse cursor inside the box to generate a private key.
833
AWS IoT Greengrass Developer Guide, Version 2
Configure your device to run IDT tests
5. From the Conversions menu, choose Export OpenSSH key, and save the private key with a .pem file
extension.
6. Add the public key to the /home/<user>/.ssh/authorized_keys file on device under test.
a. Copy the public key text from the PuTTYgen window.
b. Use PuTTY to create a session on your device under test.
i. From a command prompt or Windows Powershell window, run the following command:
C:/<path-to-putty>/putty.exe -ssh <user>@<dut-ip-address>
ii. When prompted, enter your device's password.
iii. Use vi or another text editor to append the public key to the /home/<user>/.ssh/
authorized_keys file on your device under test.
7. Update your device.json file with your user name, the IP address, and path to the private key file
that you just saved on your host computer for each device under test. For more information, see
the section called “Configure device.json” (p. 837). Make sure you provide the full path and file
name to the private key and use forward slashes ('/'). For example, for the Windows path C:\DT
\privatekey.pem, use C:/DT/privatekey.pem in the device.json file.
Configure the default Greengrass user for Windows devices
To qualify a Windows-based device, you must create the default Greengrass user in the LocalSystem
account on the device under test, and then store the user name and password for the default user in the
Credential Manager instance for the LocalSystem account.
1. Open the Windows Command Prompt (cmd.exe) as an administrator.
2. Create the default user in the LocalSystem account on the Windows device. Replace password with
a secure password.
net user /add ggc_user password
3. Download and install the PsExec utility from Microsoft on the device.
4. Use the PsExec utility to store the user name and password for the default user in the Credential
Manager instance for the LocalSystem account. Replace password with the user's password that you
set earlier.
psexec -s cmd /c cmdkey /generic:ggc_user /user:ggc_user /pass:password
If the PsExec License Agreement opens, choose Accept to agree to the license and run the
command.
Note
On Windows devices, the LocalSystem account runs the Greengrass nucleus, and you must
use the PsExec utility to store the default user information in the LocalSystem account.
Using the Credential Manager application stores this information in the Windows account of
the currently logged on user, instead of the LocalSystem account.
Configure user permissions on your device
IDT performs operations on various directories and files in a device under test. Some of these operations
require elevated permissions (using sudo). To automate these operations, IDT for AWS IoT Greengrass V2
must be able to run commands with sudo without being prompted for a password.
Follow these steps on the device under test to allow sudo access without being prompted for a password.
834
AWS IoT Greengrass Developer Guide, Version 2
Configure your device to run IDT tests
Note
username refers to the SSH user used by IDT to access the device under test.
To add the user to the sudo group
1. On the device under test, run sudo usermod -aG sudo <username>.
2. Sign out and then sign back in for changes to take effect.
3. To verify your user name was added successfully, run sudo echo test. If you are not prompted for a
password, your user is configured correctly.
4. Open the /etc/sudoers file and add the following line to the end of the file:
<ssh-username> ALL=(ALL) NOPASSWD: ALL
Configure your device to test optional features
This section describes the device requirements to run IDT tests for optional Docker and machine learning
(ML) features. You must make sure your device meets these requirements only if you want to test these
features. Otherwise, continue to the section called “Configure IDT settings” (p. 836).
Topics
• Docker qualification requirements (p. 835)
• ML qualification requirements (p. 836)
Docker qualification requirements
IDT for AWS IoT Greengrass V2 provides Docker qualification tests to validate that your devices can
use the AWS-provided Docker application manager (p. 216) component to download Docker container
images that you can run using custom Docker container components. For information about creating
custom Docker components, see Run a Docker container (p. 456).
To run Docker qualification tests, your devices under test must meet the following requirements to
deploy the Docker application manager component.
• Docker Engine 1.9.1 or later installed on your Greengrass core device. Version 20.10 is the latest
version that is verified to work with the connector. You must install Docker directly on the core device
before you deploy custom components that run Docker containers.
• The Docker daemon started and running on the core device before you deploy this component.
• The system user that runs a Docker container component must have root or administrator permissions,
or you must configure Docker to run it as a non-root or non-admistrator user. On Linux devices, you
can add a user to the docker group to call docker commands without sudo. On Windows devices,
you can add a user to the docker-users group to call docker commands without adminstrator
privileges.
On Linux, to add ggc_user, or the non-root user that you use to run AWS IoT Greengrass, to the
docker group that you configure, run the following command.
sudo usermod -aG docker user-name
For more information, see the following Docker documentation:
• Linux: Manage Docker as a non-root user
• Windows: Install Docker Desktop on Windows
835
AWS IoT Greengrass Developer Guide, Version 2
Configure IDT settings
ML qualification requirements
IDT for AWS IoT Greengrass V2 provides ML qualification tests to validate that your devices can use the
AWS-provided machine learning components (p. 288) to perform ML inference locally using the Deep
Learning Runtime or TensorFlow Lite ML frameworks. For more information about running ML inference
on Greengrass devices, see Perform machine learning inference (p. 723).
To run ML qualification tests, your devices under test must meet the following requirements to deploy
the machine learning components.
• On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, GNU C Library (glibc) version
2.27 or later installed on the device.
• On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device.
Run the following command to install the dependencies.
sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-
dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
• On Raspberry Pi devices, OpenCV-Python installed on the device. Run the following command to
install OpenCV-Python.
pip3 install opencv-python
Configure IDT settings to run the AWS IoT Greengrass
qualification suite
Before you run tests, you must configure settings for AWS credentials and devices on your host
computer.
Configure AWS credentials in config.json
You must configure your IAM user credentials in the <device_tester_extract_location>/
configs/config.json file. Use the credentials for the IDT for AWS IoT Greengrass V2 user created in
the section called “Create and configure an AWS account” (p. 825). You can specify your credentials in
one of two ways:
• In a credentials file
• As environment variables
Configure AWS credentials with a credentials file
IDT uses the same credentials file as the AWS CLI. For more information, see Configuration and credential
files.
The location of the credentials file varies, depending on the operating system you are using:
• macOS, Linux: ~/.aws/credentials
• Windows: C:\Users\UserName\.aws\credentials
Add your AWS credentials to the credentials file in the following format:
[default]
aws_access_key_id = <your_access_key_id>
836
AWS IoT Greengrass Developer Guide, Version 2
Configure IDT settings
aws_secret_access_key = <your_secret_access_key>
To configure IDT for AWS IoT Greengrass V2 to use AWS credentials from your credentials file, edit
your config.json file as follows:
{
"awsRegion": "region",
"auth": {
"method": "file",
"credentials": {
"profile": "default"
}
}
}
Note
If you do not use the default AWS profile, be sure to change the profile name in your
config.json file. For more information, see Named profiles.
Configure AWS credentials with environment variables
Environment variables are variables maintained by the operating system and used by system
commands. They are not saved if you close the SSH session. IDT for AWS IoT Greengrass V2 can use
the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables to store your AWS
credentials.
To set these variables on Linux, macOS, or Unix, use export:
export AWS_ACCESS_KEY_ID=<your_access_key_id>
export AWS_SECRET_ACCESS_KEY=<your_secret_access_key>
To set these variables on Windows, use set:
set AWS_ACCESS_KEY_ID=<your_access_key_id>
set AWS_SECRET_ACCESS_KEY=<your_secret_access_key>
To configure IDT to use the environment variables, edit the auth section in your config.json file. Here
is an example:
{
"awsRegion": "region",
"auth": {
"method": "environment"
}
}
Configure device.json
In addition to AWS credentials, IDT for AWS IoT Greengrass V2 needs information about the devices that
tests are run on. Example information would be IP address, login information, operating system, and CPU
architecture.
You must provide this information using the device.json template located in
<device_tester_extract_location>/configs/device.json:
[
{
"id": "<pool-id>",
"sku": "<sku>",
837
AWS IoT Greengrass Developer Guide, Version 2
Configure IDT settings
"features": [
{
"name": "arch",
"value": "x86_64 | armv6l | armv7l | aarch64"
},
{
"name": "ml",
"value": "dlr | tensorflowlite | dlr,tensorflowlite | no"
},
{
"name": "docker",
"value": "yes | no"
},
{
"name": "streamManagement",
"value": "yes | no"
}
],
"devices": [
{
"id": "<device-id>",
"operatingSystem": "Linux | Windows",
"connectivity": {
"protocol": "ssh",
"ip": "<ip-address>",
"port": 22,
"publicKeyPath": "<public-key-path>",
"auth": {
"method": "pki | password",
"credentials": {
"user": "<user-name>",
"privKeyPath": "/path/to/private/key",
"password": "<password>"
}
}
}
}
]
}
]
Note
Specify privKeyPath only if method is set to pki.
Specify password only if method is set to password.
All properties that contain values are required, as described here:
id
A user-defined alphanumeric ID that uniquely identifies a collection of devices called a device pool.
Devices that belong to a pool must have identical hardware. When you run a suite of tests, devices in
the pool are used to parallelize the workload. Multiple devices are used to run different tests.
sku
An alphanumeric value that uniquely identifies the device under test. The SKU is used to track
qualified boards.
Note
If you want to list your device in the AWS Partner Device Catalog, the SKU you specify here
must match the SKU that you use in the listing process.
features
An array that contains the device's supported features. All features are required.
838
AWS IoT Greengrass Developer Guide, Version 2
Configure IDT settings
arch
The supported operating system architectures that the test run validates. Valid values are:
• x86_64
• armv6l
• armv7l
• aarch64
ml
Validates that the device meets all of the required technical dependencies to use the AWS-
provided machine learning (ML) components.
Enabling this feature also validates that the device can perform ML inference using the Deep
Learning Runtime and TensorFlow Lite ML frameworks.
Valid values are any combination of dlr and tensorflowlite, or no.
docker
Validates that the device meets all required technical dependencies to use the AWS-provided
Docker application manager (aws.greengrass.DockerApplicationManager) component.
Enabling this feature also validates that the device can download a Docker container image from
Amazon Elastic Container Registry (Amazon ECR).
Valid values are any combination of yes or no.
streamManagement
Validates that the device can download, install, and run the AWS IoT Greengrass stream
manager (p. 682).
Valid values are any combination of yes or no.
Note
IDT v4.2.0 and later versions support testing the ml, docker, and streamManagement
features. If you don't want to test these features, set the corresponding value to no.
devices.id
A user-defined unique identifier for the device being tested.
devices.operatingSystem
The device operating system. Supported values are Linux and Windows.
connectivity.protocol
The communication protocol used to communicate with this device. Currently, the only supported
value is ssh for physical devices.
connectivity.ip
The IP address of the device being tested.
This property applies only if connectivity.protocol is set to ssh.
connectivity.port
Optional. The port number to use for SSH connections.
The default value is 22.
This property applies only if connectivity.protocol is set to ssh.
connectivity.publicKeyPath
Optional. The full path to the public key used to authenticate connections to the device under test.
839
AWS IoT Greengrass Developer Guide, Version 2
Configure IDT settings
When you specify the publicKeyPath, IDT validates the device’s public key when it establishes an
SSH connection to the device under test. If this value is not specified, IDT creates an SSH connection,
but doesn’t validate the device’s public key.
We strongly recommend that you specify the path to the public key, and that you use a secure
method to fetch this public key. For standard command line-based SSH clients, the public key is
provided in the known_hosts file. If you specify a separate public key file, this file must use the
same format as the known_hosts file, that is, ip-address key-type public-key.
connectivity.auth
Authentication information for the connection.
This property applies only if connectivity.protocol is set to ssh.
connectivity.auth.method
The authentication method used to access a device over the given connectivity protocol.
Supported values are:
• pki
• password
connectivity.auth.credentials
The credentials used for authentication.
connectivity.auth.credentials.password
The password used for signing in to the device being tested.
This value applies only if connectivity.auth.method is set to password.
connectivity.auth.credentials.privKeyPath
The full path to the private key used to sign in to the device under test.
This value applies only if connectivity.auth.method is set to pki.
connectivity.auth.credentials.user
The user name for signing in to the device being tested.
Configure userdata.json
IDT for AWS IoT Greengrass V2 also needs additional information about the location of test artifacts and
AWS IoT Greengrass software.
You must provide this information using the userdata.json template located in
<device_tester_extract_location>/configs/userdata.json:
{
"TempResourcesDirOnDevice": "/path/to/temp/folder",
"InstallationDirRootOnDevice": "/path/to/installation/folder",
"GreengrassNucleusZip": "/path/to/aws.greengrass.nucleus.zip",
"GreengrassV2TokenExchangeRole": "custom-iam-role-name"
}
All properties that contain values are required as described here:
TempResourcesDirOnDevice
The full path to a temporary folder on the device under test in which to store test artifacts. Make
sure that sudo permissions are not required to write to this directory.
840
AWS IoT Greengrass Developer Guide, Version 2
Configure IDT settings
Note
IDT deletes the contents of this folder when it finishes running a test.
InstallationDirRootOnDevice
The full path to a folder on the device in which to install AWS IoT Greengrass.
You must set the required file permissions for this folder. Run the following command for each
folder in the installation path.
sudo chmod 755 folder-name
GreengrassNucleusZip
The full path to the Greengrass nucleus ZIP (greengrass-nucleus-latest.zip) file on your host
computer.
GreengrassV2TokenExchangeRole
Optional. The custom IAM role that you want to use as the token exchange role that the device
under test assumes to interact with AWS resources.
Note
IDT uses this custom IAM role instead of creating the default token exchange role during
the test run. If you use a custom role, you can update the IAM permissions for the test
user (p. 826) to exclude the iamResourcesUpdate statement that allows the user to
create and delete IAM roles and policies.
Your custom IAM role must meet the following requirements. We strongly recommend that you add
only the minimum required policy actions to this role.
• The name of the custom IAM role must match the IAM role resource that you specify in the IAM
permissions for the test user. By default, the test user policy (p. 826) allows access to IAM roles
that have the idt- prefix in their role names. If your IAM role name doesn't use this prefix, add
the arn:aws:iam::*:role/custom-iam-role-name resource to the roleAliasResources
statement and the passRoleForResources statement in your policy, as shown in the following
examples:
Example passRoleForResources statement
{
"Sid":"passRoleForResources",
"Effect":"Allow",
"Action":"iam:PassRole",
"Resource":"arn:aws:iam::*:role/custom-iam-role-name",
"Condition":{
"StringEquals":{
"iam:PassedToService":[
"iot.amazonaws.com",
"lambda.amazonaws.com",
"greengrass.amazonaws.com"
]
}
}
}
Example roleAliasResources statement
841
AWS IoT Greengrass Developer Guide, Version 2
Configure IDT settings
"Sid":"roleAliasResources",
"Effect":"Allow",
"Action":[
"iot:CreateRoleAlias",
"iot:DescribeRoleAlias",
"iot:DeleteRoleAlias",
"iot:TagResource",
"iam:GetRole"
],
"Resource":[
"arn:aws:iot:*:*:rolealias/idt-*",
"arn:aws:iam::*:role/custom-iam-role-name"
]
}
• The custom IAM role must be configured with the following minimum trust policy:
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Principal":{
"Service":[
"credentials.iot.amazonaws.com",
"lambda.amazonaws.com",
"sagemaker.amazonaws.com"
]
},
"Action":"sts:AssumeRole"
}
]
}
• The custom IAM role must be configured with the following minimum permissions policy:
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"iot:DescribeCertificate",
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:DescribeLogStreams",
"iot:Connect",
"iot:Publish",
"iot:Subscribe",
"iot:Receive",
"iot:ListThingPrincipals",
"iot:GetThingShadow",
"iot:UpdateThingShadow",
"s3:GetBucketLocation",
"s3:GetObject",
"s3:PutObject",
"s3:AbortMultipartUpload",
"s3:ListMultipartUploadParts"
],
"Resource":"*"
}
]
}
842
AWS IoT Greengrass Developer Guide, Version 2
Run the AWS IoT Greengrass qualification suite
Note
For information about the supported versions of the Greengrass nucleus for IDT for AWS IoT
Greengrass, see Latest IDT version for AWS IoT Greengrass V2 (p. 818).
Run the AWS IoT Greengrass qualification suite
After you set the required configuration (p. 836), you can start the tests. The runtime of the full test
suite depends on your hardware. For reference, it takes approximately 30 minutes to complete the full
test suite on a Raspberry Pi 3B.
Use the following run-suite command to run a suite of tests.
devicetester_[linux | mac | win]_x86-64 run-suite \
--suite-id suite-id \
--group-id group-id \
--pool-id your-device-pool \
--test-id test-id \
--update-idt y|n \
--userdata userdata.json
The --userdata option is the only required option for the run-suite command; all other options are
optional. For example, you can omit pool-id if you have only one device pool, which is a set of identical
devices, defined in your device.json file. Or, you can omit suite-id if you want to run the latest test
suite version in the tests folder.
Note
IDT prompts you if a newer test suite version is available online. For more information, see the
section called “Test suite versions” (p. 821).
Example commands to run the qualification suite
The following command line examples show you how to run the qualification tests for a device
pool. For more information about run-suite and other IDT commands, see the section called “IDT
commands” (p. 844).
Use the following command to run all test groups in a specified test suite. The list-suites command
lists the test suites that are in the tests folder.
devicetester_[linux | mac | win]_x86-64 run-suite \
--suite-id GGV2Q_1.0.0 \
--pool-id <pool-id> \
--userdata userdata.json
Use the following command to run a specific test group in a test suite. The list-groups command lists
the test groups in a test suite.
devicetester_[linux | mac | win]_x86-64 run-suite \
--suite-id GGV2Q_1.0.0 \
--group-id <group-id> \
--pool-id <pool-id> \
--userdata userdata.json
Use the following command to run a specific test case in a test group.
devicetester_[linux | mac | win]_x86-64 run-suite \
--group-id <group-id> \
--test-id <test-id> \
--userdata userdata.json
843
AWS IoT Greengrass Developer Guide, Version 2
Run the AWS IoT Greengrass qualification suite
Use the following command to run multiple test cases in a test group.
devicetester_[linux | mac | win]_x86-64 run-suite \
--group-id <group-id> \
--test-id <test-id1>,<test-id2>
--userdata userdata.json
Use the following command to list all of the test cases in a test group.
devicetester_[linux | mac | win]_x86-64 list-test-cases --group-id <group-id>
We recommend that you run the dependency checker test group to make sure all Greengrass
dependencies are installed before you run related test groups. For example:
• Run coredependencies before running core qualification test groups.
IDT for AWS IoT Greengrass V2 commands
The IDT commands are located in the <device-tester-extract-location>/bin directory. To run a
test suite, you provide the command in the following format:
help
Lists information about the specified command.
list-groups
Lists the groups in a given test suite.
list-suites
Lists the available test suites.
list-supported-products
Lists the supported products, in this case AWS IoT Greengrass versions, and test suite versions for
the current IDT version.
list-test-cases
Lists the test cases in a given test group. The following option is supported:
• group-id. The test group to search for. This option is required and must specify a single group.
run-suite
Runs a suite of tests on a pool of devices. The following are some supported options:
• suite-id. The test suite version to run. If not specified, IDT uses the latest version in the tests
folder.
• group-id. The test groups to run, as a comma-separated list. If not specified, IDT runs all test
groups in the test suite.
• test-id. The test cases to run, as a comma-separated list. When specified, group-id must
specify a single group.
• pool-id. The device pool to test. You must specify a pool if you have multiple device pools
defined in your device.json file.
• stop-on-first-failure. Configures IDT to stop running on the first failure. Use this option
with group-id when you want to debug the specified test groups. Do not use this option when
running a full test-suite to generate a qualification report.
• update-idt. Sets the response for the prompt to update IDT. The Y response stops the test
execution if IDT detects there is a newer version. The N response continues the test execution.
844
AWS IoT Greengrass Developer Guide, Version 2
Understanding results and logs
• userdata. The full path to the userdata.json file that contains information about test artifact
paths. This option is required for the run-suite command. The userdata.json file must be
located in the devicetester_extract_location/devicetester_ggv2_[win|mac|linux]/
configs/ directory.
For more information about run-suite options, use the help option:
devicetester_[linux | mac | win_x86-64] run-suite -h
Understanding results and logs
This section describes how to view and interpret IDT result reports and logs.
Viewing results
While running, IDT writes errors to the console, log files, and test reports. After IDT completes the
qualification test suite, it generates two test reports. These reports are located in <device-tester-
extract-location>/results/<execution-id>/. Both reports capture the results from running the
qualification test suite.
The awsiotdevicetester_report.xml is the qualification test report that you submit to AWS to list
your device in the AWS Partner Device Catalog. The report contains the following elements:
• The IDT version.
• The AWS IoT Greengrass version that was tested.
• The SKU and the device pool name specified in the device.json file.
• The features of the device pool specified in the device.json file.
• The aggregate summary of test results.
• A breakdown of test results by libraries that were tested based on the device features, such as local
resource access, shadow, and MQTT.
The GGV2Q_Result.xml report is in JUnit XML format. You can integrate it into continuous integration
and deployment platforms like Jenkins, Bamboo, and so on. The report contains the following elements:
• Aggregate summary of test results.
• Breakdown of test results by the AWS IoT Greengrass functionality that was tested.
Interpreting AWS IoT Device Tester results
The report section in awsiotdevicetester_report.xml or awsiotdevicetester_report.xml
lists the tests that were run and the results.
The first XML tag <testsuites> contains the summary of the test run. For example:
<testsuites name="GGQ results" time="2299" tests="28" failures="0" errors="0" disabled="0">
Attributes used in the <testsuites> tag
name
The name of the test suite.
845
AWS IoT Greengrass Developer Guide, Version 2
Understanding results and logs
time
The time, in seconds, that it took to run the qualification suite.
tests
The number of tests that were run.
failures
The number of tests that were run, but did not pass.
errors
The number of tests that IDT couldn't run.
disabled
Ignore this attribute. It is not used.
The awsiotdevicetester_report.xml file contains an <awsproduct> tag that contains information
about the product being tested and the product features that were validated after running a suite of
tests.
Attributes used in the <awsproduct> tag
name
The name of the product being tested.
version
The version of the product being tested.
features
The features validated. Features marked as required are required to submit your board
for qualification. The following snippet shows how this information appears in the
awsiotdevicetester_report.xml file.
<name="aws-iot-greengrass-v2-core" value="supported" type="required"></feature>
If there are no test failures or errors for the required features, your device meets the technical
requirements to run AWS IoT Greengrass and can interoperate with AWS IoT services. If you want to list
your device in the AWS Partner Device Catalog, you can use this report as qualification evidence.
In the event of test failures or errors, you can identify the test that failed by reviewing the
<testsuites> XML tags. The <testsuite> XML tags inside the <testsuites> tag show the test
result summary for a test group. For example:
<testsuite name="combination" package="" tests="1" failures="0" time="161" disabled="0"
errors="0" skipped="0">
The format is similar to the <testsuites> tag, but with a skipped attribute that is not used and can
be ignored. Inside each <testsuite> XML tag, there are <testcase> tags for each test that was run
for a test group. For example:
<testcase classname="Security Combination (IPD + DCM) Test Context" name="Security
Combination IP Change Tests sec4_test_1: Should rotate server cert when IPD disabled
and following changes are made:Add CIS conn info and Add another CIS conn info"
attempts="1"></testcase>>
846
AWS IoT Greengrass Developer Guide, Version 2
Use IDT to develop and run your own test suites
Attributes used in the <testcase> tag
name
The name of the test.
attempts
The number of times IDT ran the test case.
When a test fails or an error occurs, <failure> or <error> tags are added to the <testcase> tag with
information for troubleshooting. For example:
<testcase classname="mcu.Full_MQTT" name="AFQP_MQTT_Connect_HappyCase" attempts="1">
<failure type="Failure">Reason for the test failure</failure>
<error>Reason for the test execution error</error>
</testcase>
Viewing logs
IDT generates logs from test runs in <devicetester-extract-location>/results/<execution-
id>/logs. Two sets of logs are generated:
test_manager.log
Logs generated from the Test Manager component of AWS IoT Device Tester (for example, logs
related to configuration, test sequencing, and report generation).
<test-case-id>.log (for example, lambdaDeploymentTest.log)
Logs of the test case within the test group, including logs from the device under test. Starting with
IDT v4.2.0, IDT groups the test logs for each test case in a separate <test-case-id> folder within
the <devicetester-extract-location>/results/<execution-id>/logs/<test-group-
id>/ directory.
Use IDT to develop and run your own test suites
Starting in IDT v4.0.1, IDT for AWS IoT Greengrass V2 combines a standardized configuration setup and
result format with a test suite environment that enables you to develop custom test suites for your
devices and device software. You can add custom tests for your own internal validation or provide them
to your customers for device verification.
Use IDT to develop and run custom test suites, as follows:
To develop custom test suites
• Create test suites with custom test logic for the Greengrass device that you want to test.
• Provide IDT with your custom test suites to test runners. Include information about specific
settings configurations for your test suites.
To run custom test suites
• Set up the device that you want to test.
• Implement the settings configurations as required by the test suites that you want to use.
• Use IDT to run your custom test suites.
• View the test results and execution logs for the tests run by IDT.
847
AWS IoT Greengrass Developer Guide, Version 2
Download the latest version of IDT for AWS IoT Greengrass
Download the latest version of AWS IoT Device Tester
for AWS IoT Greengrass
Download the latest version (p. 818) of IDT and extract the software into a location (<device-
tester-extract-location>) on your file system where you have read/write permissions.
Note
IDT does not support being run by multiple users from a shared location, such as an NFS
directory or a Windows network shared folder. We recommend that you extract the IDT package
to a local drive and run the IDT binary on your local workstation.
Windows has a path length limitation of 260 characters. If you are using Windows, extract IDT to
a root directory like C:\ or D:\ to keep your paths under the 260 character limit.
Test suite creation workflow
Test suites are composed of three types of files:
• JSON configuration files that provide IDT with information on how to execute the test suite.
• Test executable files that IDT uses to run test cases.
• Additional files required to run tests.
Complete the following basic steps to create custom IDT tests:
1. Create JSON configuration files (p. 858) for your test suite.
2. Create test case executables (p. 879) that contain the test logic for your test suite.
3. Verify and document the configuration information required for test runners (p. 886) to run the
test suite.
4. Verify that IDT can run your test suite and produce test results (p. 894) as expected.
To quickly build a sample custom suite and run it, follow the instructions in Tutorial: Build and run the
sample IDT test suite (p. 848).
To get started creating a custom test suite in Python, see Tutorial: Develop a simple IDT test
suite (p. 852).
Tutorial: Build and run the sample IDT test suite
The AWS IoT Device Tester download includes the source code for a sample test suite. You can complete
this tutorial to build and run the sample test suite to understand how you can use IDT for AWS IoT
Greengrass to run custom test suites.
In this tutorial, you will complete the following steps:
1. Build the sample test suite (p. 850)
2. Use IDT to run the sample test suite (p. 851)
Prerequisites
To complete this tutorial, you need the following:
• Host computer requirements
• Latest version of AWS IoT Device Tester
848
AWS IoT Greengrass Developer Guide, Version 2
Tutorial: Build and run the sample IDT test suite
• Python 3.7 or later
To check the version of Python installed on your computer, run the following command:
python3 --version
On Windows, if using this command returns an error, then use python --version instead. If the
returned version number is 3.7 or greater, then run the following command in a Powershell terminal
to set python3 as an alias for your python command.
Set-Alias -Name "python3" -Value "python"
If no version information is returned or if the version number is less than 3.7, follow the
instructions in Downloading Python to install Python 3.7+. For more information, see the Python
documentation.
• urllib3
To verify that urllib3 is installed correctly, run the following command:
python3 -c 'import urllib3'
If urllib3 is not installed, run the following command to install it:
python3 -m pip install urllib3
• Device requirements
• A device with a Linux operating system and a network connection to the same network as your host
computer.
We recommend that you use a Raspberry Pi with Raspberry Pi OS. Make sure you set up SSH on your
Raspberry Pi to remotely connect to it.
Configure device information for IDT
Configure your device information for IDT to run the test. You must update the device.json
template located in the <device-tester-extract-location>/configs folder with the following
information.
[
{
"id": "pool",
"sku": "N/A",
"devices": [
{
"id": "<device-id>",
"connectivity": {
"protocol": "ssh",
"ip": "<ip-address>",
"port": "<port>",
"auth": {
"method": "pki | password",
"credentials": {
"user": "<user-name>",
"privKeyPath": "/path/to/private/key",
"password": "<password>"
}
849
AWS IoT Greengrass Developer Guide, Version 2
Tutorial: Build and run the sample IDT test suite
}
}
}
]
}
]
In the devices object, provide the following information:
id
A user-defined unique identifier for your device.
connectivity.ip
The IP address of your device.
connectivity.port
Optional. The port number to use for SSH connections to your device.
connectivity.auth
Authentication information for the connection.
This property applies only if connectivity.protocol is set to ssh.
connectivity.auth.method
The authentication method used to access a device over the given connectivity protocol.
Supported values are:
• pki
• password
connectivity.auth.credentials
The credentials used for authentication.
connectivity.auth.credentials.user
The user name used to sign in to your device.
connectivity.auth.credentials.privKeyPath
The full path to the private key used to sign in to your device.
This value applies only if connectivity.auth.method is set to pki.
devices.connectivity.auth.credentials.password
The password used for signing in to your device.
This value applies only if connectivity.auth.method is set to password.
Note
Specify privKeyPath only if method is set to pki.
Specify password only if method is set to password.
Build the sample test suite
The <device-tester-extract-location>/samples/python folder contains sample configuration
files, source code, and the IDT Client SDK that you can combine into a test suite using the provided build
scripts. The following directory tree shows the location of these sample files:
<device-tester-extract-location>
850
AWS IoT Greengrass Developer Guide, Version 2
Tutorial: Build and run the sample IDT test suite
### ...
### tests
### samples
# ### ...
# ### python
# ### configuration
# ### src
# ### build-scripts
# ### build.sh
# ### build.ps1
### sdks
### ...
### python
### idt_client
To build the test suite, run the following commands on your host computer:
Windows
cd <device-tester-extract-location>/samples/python/build-scripts
./build.ps1
Linux, macOS, or UNIX
cd <device-tester-extract-location>/samples/python/build-scripts
./build.sh
This creates the sample test suite in the IDTSampleSuitePython_1.0.0 folder within the <device-
tester-extract-location>/tests folder. Review the files in the IDTSampleSuitePython_1.0.0
folder to understand how the sample test suite is structured and see various examples of test case
executables and test configuration JSON files.
Next step: Use IDT to run the sample test suite (p. 851) that you created.
Use IDT to run the sample test suite
To run the sample test suite, run the following commands on your host computer:
cd <device-tester-extract-location>/bin
./devicetester_[linux | mac | win_x86-64] run-suite --suite-id IDTSampleSuitePython
IDT runs the sample test suite and streams the results to the console. When the test has finished running,
you see the following information:
========== Test Summary ==========
Execution Time: 5s
Tests Completed: 4
Tests Passed: 4
Tests Failed: 0
Tests Skipped: 0
----------------------------------
Test Groups:
sample_group: PASSED
----------------------------------
Path to IoT Device Tester Report: /path/to/devicetester/
results/87e673c6-1226-11eb-9269-8c8590419f30/awsiotdevicetester_report.xml
Path to Test Execution Logs: /path/to/devicetester/
results/87e673c6-1226-11eb-9269-8c8590419f30/logs
851
AWS IoT Greengrass Developer Guide, Version 2
Tutorial: Develop a simple IDT test suite
Path to Aggregated JUnit Report: /path/to/devicetester/
results/87e673c6-1226-11eb-9269-8c8590419f30/IDTSampleSuitePython_Report.xml
Troubleshooting
Use the following information to help resolve any issues with completing the tutorial.
Test case does not run successfully
If the test does not run successfully, IDT streams the error logs to the console that can help you
troubleshoot the test run. Make sure that you meet all the prerequisites (p. 848) for this tutorial.
Cannot connect to the device under test
Verify the following:
• Your device.json file contains the correct IP address, port, and authentication information.
• You can connect to your device over SSH from your host computer.
Tutorial: Develop a simple IDT test suite
A test suite combines the following:
• Test executables that contain the test logic
• JSON configuration files that describe the test suite
This tutorial shows you how to use IDT for AWS IoT Greengrass to develop a Python test suite that
contains a single test case. In this tutorial, you will complete the following steps:
1. Create a test suite directory (p. 853)
2. Create JSON configuration files (p. 853)
3. Create the test case executable (p. 855)
4. Run the test suite (p. 857)
Prerequisites
To complete this tutorial, you need the following:
• Host computer requirements
• Latest version of AWS IoT Device Tester
• Python 3.7 or later
To check the version of Python installed on your computer, run the following command:
python3 --version
On Windows, if using this command returns an error, then use python --version instead. If the
returned version number is 3.7 or greater, then run the following command in a Powershell terminal
to set python3 as an alias for your python command.
Set-Alias -Name "python3" -Value "python"
852
AWS IoT Greengrass Developer Guide, Version 2
Tutorial: Develop a simple IDT test suite
If no version information is returned or if the version number is less than 3.7, follow the
instructions in Downloading Python to install Python 3.7+. For more information, see the Python
documentation.
• urllib3
To verify that urllib3 is installed correctly, run the following command:
python3 -c 'import urllib3'
If urllib3 is not installed, run the following command to install it:
python3 -m pip install urllib3
• Device requirements
• A device with a Linux operating system and a network connection to the same network as your host
computer.
We recommend that you use a Raspberry Pi with Raspberry Pi OS. Make sure you set up SSH on your
Raspberry Pi to remotely connect to it.
Create a test suite directory
IDT logically separates test cases into test groups within each test suite. Each test case must be inside
a test group. For this tutorial, create a folder called MyTestSuite_1.0.0 and create the following
directory tree within this folder:
MyTestSuite_1.0.0
### suite
### myTestGroup
### myTestCase
Create JSON configuration files
Your test suite must contain the following required JSON configuration files (p. 858):
Required JSON files
suite.json
Contains information about the test suite. See Configure suite.json (p. 859).
group.json
Contains information about a test group. You must create a group.json file for each test group in
your test suite. See Configure group.json (p. 860).
test.json
Contains information about a test case. You must create a test.json file for each test case in your
test suite. See Configure test.json (p. 860).
1. In the MyTestSuite_1.0.0/suite folder, create a suite.json file with the following structure:
853
AWS IoT Greengrass Developer Guide, Version 2
Tutorial: Develop a simple IDT test suite
"id": "MyTestSuite_1.0.0",
"title": "My Test Suite",
"details": "This is my test suite.",
"userDataRequired": false
}
2. In the MyTestSuite_1.0.0/myTestGroup folder, create a group.json file with the following
structure:
{
"id": "MyTestGroup",
"title": "My Test Group",
"details": "This is my test group.",
"optional": false
}
3. In the MyTestSuite_1.0.0/myTestGroup/myTestCase folder, create a test.json file with the
following structure:
{
"id": "MyTestCase",
"title": "My Test Case",
"details": "This is my test case.",
"execution": {
"timeout": 300000,
"linux": {
"cmd": "python3",
"args": [
"myTestCase.py"
]
},
"mac": {
"cmd": "python3",
"args": [
"myTestCase.py"
]
},
"win": {
"cmd": "python3",
"args": [
"myTestCase.py"
]
}
}
}
The directory tree for your MyTestSuite_1.0.0 folder should now look like the following:
MyTestSuite_1.0.0
### suite
### suite.json
### myTestGroup
### group.json
### myTestCase
### test.json
Get the IDT client SDK
You use the IDT client SDK (p. 879) to enable IDT to interact with the device under test and to report
test results. For this tutorial, you will use the Python version of the SDK.
854
AWS IoT Greengrass Developer Guide, Version 2
Tutorial: Develop a simple IDT test suite
From the <device-tester-extract-location>/sdks/python/ folder, copy the idt_client
folder to your MyTestSuite_1.0.0/suite/myTestGroup/myTestCase folder.
To verify that the SDK was successfully copied, run the following command.
cd MyTestSuite_1.0.0/suite/myTestGroup/myTestCase
python3 -c 'import idt_client'
Create the test case executable
Test case executables contain the test logic that you want to run. A test suite can contain multiple test
case executables. For this tutorial, you will create only one test case executable.
1. Create the test suite file.
In the MyTestSuite_1.0.0/suite/myTestGroup/myTestCase folder, create a myTestCase.py
file with the following content:
from idt_client import *
def main():
# Use the client SDK to communicate with IDT
client = Client()
if __name__ == "__main__":
main()
2. Use client SDK functions to add the following test logic to your myTestCase.py file:
a. Run an SSH command on the device under test.
from idt_client import *
def main():
# Use the client SDK to communicate with IDT
client = Client()
# Create an execute on device request
exec_req = ExecuteOnDeviceRequest(ExecuteOnDeviceCommand("echo 'hello world'"))
# Run the command
exec_resp = client.execute_on_device(exec_req)
# Print the standard output
print(exec_resp.stdout)
if __name__ == "__main__":
main()
b. Send the test result to IDT.
from idt_client import *
def main():
# Use the client SDK to communicate with IDT
client = Client()
# Create an execute on device request
exec_req = ExecuteOnDeviceRequest(ExecuteOnDeviceCommand("echo 'hello world'"))
# Run the command
855
AWS IoT Greengrass Developer Guide, Version 2
Tutorial: Develop a simple IDT test suite
exec_resp = client.execute_on_device(exec_req)
# Print the standard output
print(exec_resp.stdout)
# Create a send result request
sr_req = SendResultRequest(TestResult(passed=True))
# Send the result
client.send_result(sr_req)
if __name__ == "__main__":
main()
Configure device information for IDT
Configure your device information for IDT to run the test. You must update the device.json
template located in the <device-tester-extract-location>/configs folder with the following
information.
[
{
"id": "pool",
"sku": "N/A",
"devices": [
{
"id": "<device-id>",
"connectivity": {
"protocol": "ssh",
"ip": "<ip-address>",
"port": "<port>",
"auth": {
"method": "pki | password",
"credentials": {
"user": "<user-name>",
"privKeyPath": "/path/to/private/key",
"password": "<password>"
}
}
}
}
]
}
]
In the devices object, provide the following information:
id
A user-defined unique identifier for your device.
connectivity.ip
The IP address of your device.
connectivity.port
Optional. The port number to use for SSH connections to your device.
connectivity.auth
Authentication information for the connection.
856
AWS IoT Greengrass Developer Guide, Version 2
Tutorial: Develop a simple IDT test suite
This property applies only if connectivity.protocol is set to ssh.
connectivity.auth.method
The authentication method used to access a device over the given connectivity protocol.
Supported values are:
• pki
• password
connectivity.auth.credentials
The credentials used for authentication.
connectivity.auth.credentials.user
The user name used to sign in to your device.
connectivity.auth.credentials.privKeyPath
The full path to the private key used to sign in to your device.
This value applies only if connectivity.auth.method is set to pki.
devices.connectivity.auth.credentials.password
The password used for signing in to your device.
This value applies only if connectivity.auth.method is set to password.
Note
Specify privKeyPath only if method is set to pki.
Specify password only if method is set to password.
Run the test suite
After you create your test suite, you want to make sure that it functions as expected. Complete the
following steps to run the test suite with your existing device pool to do so.
1. Copy your MyTestSuite_1.0.0 folder into <device-tester-extract-location>/tests.
2. Run the following commands:
cd <device-tester-extract-location>/bin
./devicetester_[linux | mac | win_x86-64] run-suite --suite-id MyTestSuite
IDT runs your test suite and streams the results to the console. When the test has finished running, you
see the following information:
time="2020-10-19T09:24:47-07:00" level=info msg=Using pool: pool
time="2020-10-19T09:24:47-07:00" level=info msg=Using test suite "MyTestSuite_1.0.0" for
execution
time="2020-10-19T09:24:47-07:00" level=info msg=b'hello world\n'
suiteId=MyTestSuite groupId=myTestGroup testCaseId=myTestCase deviceId=my-device
executionId=9a52f362-1227-11eb-86c9-8c8590419f30
time="2020-10-19T09:24:47-07:00" level=info msg=All tests finished.
executionId=9a52f362-1227-11eb-86c9-8c8590419f30
time="2020-10-19T09:24:48-07:00" level=info msg=
========== Test Summary ==========
Execution Time: 1s
Tests Completed: 1
Tests Passed: 1
857
AWS IoT Greengrass Developer Guide, Version 2
Create IDT test suite configuration files
Tests Failed: 0
Tests Skipped: 0
----------------------------------
Test Groups:
myTestGroup: PASSED
----------------------------------
Path to IoT Device Tester Report: /path/to/devicetester/
results/9a52f362-1227-11eb-86c9-8c8590419f30/awsiotdevicetester_report.xml
Path to Test Execution Logs: /path/to/devicetester/
results/9a52f362-1227-11eb-86c9-8c8590419f30/logs
Path to Aggregated JUnit Report: /path/to/devicetester/
results/9a52f362-1227-11eb-86c9-8c8590419f30/MyTestSuite_Report.xml
Troubleshooting
Use the following information to help resolve any issues with completing the tutorial.
Test case does not run successfully
If the test does not run successfully, IDT streams the error logs to the console that can help you
troubleshoot the test run. Before you check the error logs, verify the following:
• The IDT client SDK is in the correct folder as described in this step (p. 854).
• You meet all the prerequisites (p. 852) for this tutorial.
Cannot connect to the device under test
Verify the following:
• Your device.json file contains the correct IP address, port, and authentication information.
• You can connect to your device over SSH from your host computer.
Create IDT test suite configuration files
This section describes the formats in which you create JSON configuration files that you include when
you write a custom test suite.
Required JSON files
suite.json
Contains information about the test suite. See Configure suite.json (p. 859).
group.json
Contains information about a test group. You must create a group.json file for each test group in
your test suite. See Configure group.json (p. 860).
test.json
Contains information about a test case. You must create a test.json file for each test case in your
test suite. See Configure test.json (p. 860).
Optional JSON files
state_machine.json
Defines how tests are run when IDT runs the test suite. See Configure state_machine.json (p. 863).
858
AWS IoT Greengrass Developer Guide, Version 2
Create IDT test suite configuration files
userdata_schema.json
Defines the schema for the userdata.json file (p. 890) that test runners can include in
their setting configuration. The userdata.json file is used for any additional configuration
information that is required to run the test but is not present in the device.json file. See
Configure userdata_schema.json (p. 863).
JSON configuration files are placed in your <custom-test-suite-folder> as shown here.
<custom-test-suite-folder>
### suite
### suite.json
### state_machine.json
### userdata_schema.json
### <test-group-folder>
### group.json
### <test-case-folder>
### test.json
Configure suite.json
The suite.json file sets environment variables and determines whether user data is required to run
the test suite. Use the following template to configure your <custom-test-suite-folder>/suite/
suite.json file:
{
"id": "<suite-name>_<suite-version>",
"title": "<suite-title>",
"details": "<suite-details>",
"userDataRequired": true | false,
"environmentVariables": [
{
"key": "<name>",
"value": "<value>",
},
...
{
"key": "<name>",
"value": "<value>",
}
]
}
All fields that contain values are required as described here:
id
A unique user-defined ID for the test suite. The value of id must match the name of the test suite
folder in which the suite.json file is located. The suite name and suite version must also meet the
following requirements:
• <suite-name> cannot contain underscores.
• <suite-version> is denoted as x.x.x, where x is a number.
The ID is shown in IDT-generated test reports.
title
A user-defined name for the product or feature being tested by this test suite. The name is displayed
in the IDT CLI for test runners.
859
AWS IoT Greengrass Developer Guide, Version 2
Create IDT test suite configuration files
details
A short description of the purpose of the test suite.
userDataRequired
Defines whether test runners need to include custom information in a userdata.json file. If you
set this value to true, you must also include the userdata_schema.json file (p. 863) in your
test suite folder.
environmentVariables
Optional. An array of environment variables to set for this test suite.
environmentVariables.key
The name of the environment variable.
environmentVariables.value
The value of the environment variable.
Configure group.json
The group.json file defines whether a test group is required or optional. Use the following template to
configure your <custom-test-suite-folder>/suite/<test-group>/group.json file:
{
"id": "<group-id>",
"title": "<group-title>",
"details": "<group-details>",
"optional": true | false,
}
All fields that contain values are required as described here:
id
A unique user-defined ID for the test group. The value of id must match the name of the test group
folder in which the group.json file is located, and can't contain underscores (_). The ID is used in
IDT-generated test reports.
title
A descriptive name for the test group. The name is displayed in the IDT CLI for test runners.
details
A short description of the purpose of the test group.
optional
Optional. Set to true to display this test group as an optional group after IDT finishes running
required tests. Default value is false.
Configure test.json
The test.json file determines the test case executables and the environment variables that are used
by a test case. For more information about creating test case executables, see Create IDT test case
executables (p. 879).
860
AWS IoT Greengrass Developer Guide, Version 2
Create IDT test suite configuration files
Use the following template to configure your <custom-test-suite-folder>/suite/<test-
group>/<test-case>/test.json file:
{
"id": "<test-id>",
"title": "<test-title>",
"details": "<test-details>",
"requireDUT": true | false,
"requiredResources": [
{
"name": "<resource-name>",
"features": [
{
"name": "<feature-name>",
"version": "<feature-version>",
"jobSlots": <job-slots>
}
]
}
],
"execution": {
"timeout": <timeout>,
"mac": {
"cmd": "/path/to/executable",
"args": [
"<argument>"
],
},
"linux": {
"cmd": "/path/to/executable",
"args": [
"<argument>"
],
},
"win": {
"cmd": "/path/to/executable",
"args": [
"<argument>"
]
}
},
"environmentVariables": [
{
"key": "<name>",
"value": "<value>",
}
]
}
All fields that contain values are required as described here:
id
A unique user-defined ID for the test case. The value of id must match the name of the test case
folder in which the test.json file is located, and can't contain underscores (_). The ID is used in
IDT-generated test reports. .
title
A descriptive name for the test case. The name is displayed in the IDT CLI for test runners.
details
A short description of the purpose of the test case.
861
AWS IoT Greengrass Developer Guide, Version 2
Create IDT test suite configuration files
requireDUT
Optional. Set to true if a device is required to run this test, otherwise set to false. Default value is
true. Test runners will configure the devices they will use to run the test in their device.json file.
requiredResources
Optional. An array that provides information about resource devices needed to run this test.
requiredResources.name
The unique name to give the resource device when this test is running.
requiredResources.features
An array of user-defined resource device features.
requiredResources.features.name
The name of the feature. The device feature for which you want to use this device.
This name is matched against the feature name provided by the test runner in the
resource.json file.
requiredResources.features.version
Optional. The version of the feature. This value is matched against the feature version
provided by the test runner in the resource.json file. If a version is not provided, then
the feature is not checked. If a version number is not required for the feature, leave this
field blank.
requiredResources.features.jobSlots
Optional. The number of simultaneous tests that this feature can support. The default value
is 1. If you want IDT to use distinct devices for individual features, then we recommend that
you set this value to 1.
execution.timeout
The amount of time (in milliseconds) that IDT waits for the test to finish running. For more
information about setting this value, see Create IDT test case executables (p. 879).
execution.os
The test case executables to run based on the operating system of the host computer that runs IDT.
Supported values are linux, mac, and win.
execution.os.cmd
The path to the test case executable that you want to run for the specified operating system.
This location must be in the system path.
execution.os.args
Optional. The arguments to provide to run the test case executable.
environmentVariables
Optional. An array of environment variables set for this test case.
environmentVariables.key
The name of the environment variable.
environmentVariables.value
The value of the environment variable.
Note
If you specify the same environment variable in the test.json file and in the suite.json
file, the value in the test.json file takes precedence.
862
AWS IoT Greengrass Developer Guide, Version 2
Configure the IDT state machine
Configure state_machine.json
A state machine is a construct that controls the test suite execution flow. It determines the starting
state of a test suite, manages state transitions based on user-defined rules, and continues to transition
through those states until it reaches the end state.
If your test suite doesn't include a user-defined state machine, IDT will generate a state machine for you.
The default state machine performs the following functions:
• Provides test runners with the ability to select and run specific test groups, instead of the entire test
suite.
• If specific test groups are not selected, runs every test group in the test suite in a random order.
• Generates reports and prints a console summary that shows the test results for each test group and
test case.
For more information about how the IDT state machine functions, see Configure the IDT state
machine (p. 863).
Configure userdata_schema.json
The userdata_schema.json file determines the schema in which test runners provide user data. User
data is required if your test suite requires information that is not present in the device.json file. For
example, your tests might need Wi-Fi network credentials, specific open ports, or certificates that a user
must provide. This information can be provided to IDT as an input parameter called userdata, the value
for which is a userdata.json file, that users create in their <device-tester-extract-location>/
config folder. The format of the userdata.json file is based on the userdata_schema.json file
that you include in the test suite.
To indicate that test runners must provide a userdata.json file:
1. In the suite.json file, set userDataRequired to true.
2. In your <custom-test-suite-folder>, create a userdata_schema.json file.
3. Edit the userdata_schema.json file to create a valid IETF Draft v4 JSON Schema.
When IDT runs your test suite, it automatically reads the schema and uses it to validate the
userdata.json file provided by the test runner. If valid, the contents of the userdata.json file are
available in both the IDT context (p. 884) and in the state machine context (p. 871).
Configure the IDT state machine
A state machine is a construct that controls the test suite execution flow. It determines the starting
state of a test suite, manages state transitions based on user-defined rules, and continues to transition
through those states until it reaches the end state.
If your test suite doesn't include a user-defined state machine, IDT will generate a state machine for you.
The default state machine performs the following functions:
• Provides test runners with the ability to select and run specific test groups, instead of the entire test
suite.
• If specific test groups are not selected, runs every test group in the test suite in a random order.
• Generates reports and prints a console summary that shows the test results for each test group and
test case.
The state machine for an IDT test suite must meet the following criteria:
863
AWS IoT Greengrass Developer Guide, Version 2
Configure the IDT state machine
• Each state corresponds to an action for IDT to take, such as to run a test group or product a report file.
• Transitioning to a state executes the action associated with the state.
• Each state defines the transition rule for the next state.
• The end state must be either Succeed or Fail.
State machine format
You can use the following template to configure your own <custom-test-suite-folder>/suite/
state_machine.json file:
{
"Comment": "<description>",
"StartAt": "<state-name>",
"States": {
"<state-name>": {
"Type": "<state-type>",
// Additional state configuration
}
// Required states
"Succeed": {
"Type": "Succeed"
},
"Fail": {
"Type": "Fail"
}
}
}
All fields that contain values are required as described here:
Comment
A description of the state machine.
StartAt
The name of the state at which IDT starts running the test suite. The value of StartAt must be set
to one of the states listed in the States object.
States
An object that maps user-defined state names to valid IDT states. Each States.state-name object
contains the definition of a valid state mapped to the state-name.
The States object must include the Succeed and Fail states. For information about valid states,
see Valid states and state definitions (p. 864).
Valid states and state definitions
This section describes the state definitions of all of the valid states that can be used in the IDT state
machine. Some of the following states support configurations at the test case level. However, we
recommend that you configure state transition rules at the test group level instead of the test case level
unless absolutely necessary.
State definitions
• RunTask (p. 865)
• Choice (p. 866)
864
AWS IoT Greengrass Developer Guide, Version 2
Configure the IDT state machine
• Parallel (p. 867)
• AddProductFeatures (p. 868)
• Report (p. 870)
• LogMessage (p. 870)
• SelectGroup (p. 870)
• Fail (p. 871)
• Succeed (p. 871)
RunTask
The RunTask state runs test cases from a test group defined in the test suite.
{
"Type": "RunTask",
"Next": "<state-name>",
"TestGroup": "<group-id>",
"TestCases": [
"<test-id>"
],
"ResultVar": "<result-name>"
}
All fields that contain values are required as described here:
Next
The name of the state to transition to after executing the actions in the current state.
TestGroup
Optional. The ID of the test group to run. If this value is not specified, then IDT runs the test group
that the test runner selects.
TestCases
Optional. An array of test case IDs from the group specified in TestGroup. Based on the values of
TestGroup and TestCases, IDT determines the test execution behavior as follows:
• When both TestGroup and TestCases are specified, IDT runs the specified test cases from the
test group.
• When TestCases are specified but TestGroup is not specified, IDT runs the specified test cases.
• When TestGroup is specified, but TestCases is not specified, IDT runs all of the test cases within
the specified test group.
• When neither TestGroup or TestCases is specified, IDT runs all test cases from the test group
that the test runner selects from the IDT CLI. To enable group selection for test runners, you must
include both RunTask and Choice states in your statemachine.json file. For an example of
how this works, see Example state machine: Run user-selected test groups (p. 875).
For more information about enabling IDT CLI commands for test runners, see the section called
“Enable IDT CLI commands” (p. 881).
ResultVar
The name of the context variable to set with the results of the test run. Do not specify this value
if you did not specify a value for TestGroup. IDT sets the value of the variable that you define in
ResultVar to true or false based on the following:
• If the variable name is of the form text_text_passed, then the value is set to whether all tests
in the first test group passed or were skipped.
• In all other cases, the value is set to whether all tests in all test groups passed or were skipped.
865
AWS IoT Greengrass Developer Guide, Version 2
Configure the IDT state machine
Typically, you will use RunTask state to specify a test group ID without specifying individual test case
IDs, so that IDT will run all of the test cases in the specified test group. All test cases that are run by this
state run in parallel, in a random order. However, if all of the test cases require a device to run, and only a
single device is available, then the test cases will run sequentially instead.
Error handling
If any of the specified test groups or test case IDs are not valid, then this state issues the RunTaskError
execution error. If the state encounters an execution error, then it also sets the hasExecutionError
variable in the state machine context to true.
Choice
The Choice state lets you dynamically set the next state to transition to based on user-defined
conditions.
{
"Type": "Choice",
"Default": "<state-name>",
"FallthroughOnError": true | false,
"Choices": [
{
"Expression": "<expression>",
"Next": "<state-name>"
}
]
}
All fields that contain values are required as described here:
Default
The default state to transition to if none of the expressions defined in Choices can be evaluated to
true.
FallthroughOnError
Optional. Specifies the behavior when the state encounters an error in evaluating expressions. Set to
true if you want to skip an expression if the evaluation results in an error. If no expressions match,
then the state machine transitions to the Default state. If the FallthroughOnError value is not
specified, it defaults to false.
Choices
An array of expressions and states to determine which state to transition to after executing the
actions in the current state.
Choices.Expression
An expression string that evaluates to a boolean value. If the expression evaluates to true, then
the state machine transitions to the state defined in Choices.Next. Expression strings retrieve
values from the state machine context and then perform operations on them to arrive at a
boolean value. For information about accesing the state machine context, see State machine
context (p. 871).
Choices.Next
The name of the state to transition to if the expression defined in Choices.Expression
evaluates to true.
Error handling
866
AWS IoT Greengrass Developer Guide, Version 2
Configure the IDT state machine
The Choice state can require error handling in the following cases:
• Some variables in the choice expressions don’t exist in the state machine context.
• The result of an expression is not a boolean value.
• The result of a JSON lookup is not a string, number, or boolean.
You cannot use a Catch block to handle errors in this state. If you want to stop executing the state
machine when it encounters an error, you must set FallthroughOnError to false. However, we
recommend that you set FallthroughOnError to true, and depending on your use case, do one of
the following:
• If a variable you are accessing is expected to not exist in some cases, then use the value of Default
and additional Choices blocks to specify the next state.
• If a variable that you are accessing should always exist, then set the Default state to Fail.
Parallel
The Parallel state lets you define and run new state machines in parallel with each other.
{
"Type": "Parallel",
"Next": "<state-name>",
"Branches": [
<state-machine-definition>
]
}
All fields that contain values are required as described here:
Next
The name of the state to transition to after executing the actions in the current state.
Branches
An array of state machine definitions to run. Each state machine definition must contain its own
StartAt, Succeed, and Fail states. The state machine definitions in this array cannot reference
states outside of their own definition.
Note
Because each branch state machine shares the same state machine context, setting
variables in one branch and then reading those variables from another branch might result
in unexpected behavior.
The Parallel state moves to the next state only after it runs all of the branch state machines. Each
state that requires a device will wait to run until the device is available. If multiple devices are available,
this state runs test cases from multiple groups in parallel. If enough devices are not available, then
test cases will run sequentially. Because test cases are run in a random order when they run in parallel,
different devices might be used to run tests from the same test group.
Error handling
Make sure that both the branch state machine and the parent state machine transition to the Fail state
to handle execution errors.
Because branch state machines do not transmit execution errors to the parent state machine, you
cannot use a Catch block to handle execution errors in branch state machines. Instead, use the
867
AWS IoT Greengrass Developer Guide, Version 2
Configure the IDT state machine
hasExecutionErrors value in the shared state machine context. For an example of how this works, see
Example state machine: Run two test groups in parallel (p. 877).
AddProductFeatures
The AddProductFeatures state lets you add product features to the
awsiotdevicetester_report.xml file generated by IDT.
A product feature is user-defined information about specific criteria that a device might meet. For
example, the MQTT product feature can designate that the device publishes MQTT messages properly.
In the report, product features are set as supported, not-supported, or a custom value, based on
whether specified tests passed.
Note
The AddProductFeatures state does not generate reports by itself. This state must transition
to the Report state (p. 870) to generate reports.
{
"Type": "Parallel",
"Next": "<state-name>",
"Features": [
{
"Feature": "<feature-name>",
"Groups": [
"<group-id>"
],
"OneOfGroups": [
"<group-id>"
],
"TestCases": [
"<test-id>"
],
"IsRequired": true | false,
"ExecutionMethods": [
"<execution-method>"
]
}
]
}
All fields that contain values are required as described here:
Next
The name of the state to transition to after executing the actions in the current state.
Features
An array of product features to show in the awsiotdevicetester_report.xml file.
Feature
The name of the feature
FeatureValue
Optional. The custom value to use in the report instead of supported. If this value is not
specified, then based on test results, the feature value is set to supported or not-supported.
If you use a custom value for FeatureValue, you can test the same feature with different
conditions, and IDT concatenates the feature values for the supported conditions. For example,
the following excerpt shows the MyFeature feature with two separate feature values:
868
AWS IoT Greengrass Developer Guide, Version 2
Configure the IDT state machine
...
{
"Feature": "MyFeature",
"FeatureValue": "first-feature-supported",
"Groups": ["first-feature-group"]
},
{
"Feature": "MyFeature",
"FeatureValue": "second-feature-supported",
"Groups": ["second-feature-group"]
},
...
If both test groups pass, then the feature value is set to first-feature-supported,
second-feature-supported.
Groups
Optional. An array of test group IDs. All tests within each specified test group must pass for the
feature to be supported.
OneOfGroups
Optional. An array of test group IDs. All tests within at least one of the specified test groups
must pass for the feature to be supported.
TestCases
Optional. An array of test case IDs. If you specify this value, then the following apply:
• All of the specified test cases must pass for the feature to be supported.
• Groups must contain only one test group ID.
• OneOfGroups must not be specified.
IsRequired
Optional. Set to false to mark this feature as an optional feature in the report. The default
value is true.
ExecutionMethods
Optional. An array of execution methods that match the protocol value specified in the
device.json file. If this value is specified, then test runners must specify a protocol value
that matches one of the values in this array to include the feature in the report. If this value is
not specified, then the feature will always be included in the report.
To use the AddProductFeatures state, you must set the value of ResultVar in the RunTask state to
one of the following values:
• If you specified individual test case IDs, then set ResultVar to group-id_test-id_passed.
• If you did not specify individual test case IDs, then set ResultVar to group-id_passed.
The AddProductFeatures state checks for test results in the following manner:
• If you did not specify any test case IDs, then the result for each test group is determined from the
value of the group-id_passed variable in the state machine context.
• If you did specify test case IDs, then the result for each of the tests is determined from the value of the
group-id_test-id_passed variable in the state machine context.
Error handling
869
AWS IoT Greengrass Developer Guide, Version 2
Configure the IDT state machine
If a group ID provided in this state is not a valid group ID, then this state results in the
AddProductFeaturesError execution error. If the state encounters an execution error, then it also
sets the hasExecutionErrors variable in the state machine context to true.
Report
The Report state generates the suite-name_Report.xml and awsiotdevicetester_report.xml
files. This state also streams the report to the console.
{
"Type": "Report",
"Next": "<state-name>"
}
All fields that contain values are required as described here:
Next
The name of the state to transition to after executing the actions in the current state.
You should always transition to the Report state towards the end of the test execution flow so that test
runners can view test results. Typically, the next state after this state is Succeed.
Error handling
If this state encounters issues with generating the reports, then it issues the ReportError execution
error.
LogMessage
The LogMessage state generates the test_manager.log file and streams the log message to the
console.
{
"Type": "LogMessage",
"Next": "<state-name>"
"Level": "info | warn | error"
"Message": "<message>"
}
All fields that contain values are required as described here:
Next
The name of the state to transition to after executing the actions in the current state.
Level
The error level at which to create the log message. If you specify a level that is not valid, this state
generates an error message and discards it.
Message
The message to log.
SelectGroup
The SelectGroup state updates the state machine context to indicate which groups are selected. The
values set by this state are used by any subsequent Choice states.
870
AWS IoT Greengrass Developer Guide, Version 2
Configure the IDT state machine
{
"Type": "SelectGroup",
"Next": "<state-name>"
"TestGroups": [
<group-id>"
]
}
All fields that contain values are required as described here:
Next
The name of the state to transition to after executing the actions in the current state.
TestGroups
An array of test groups that will be marked as selected. For each test group ID in this array, the
group-id_selected variable is set to true in the context. Make sure that you provide valid test
group IDs because IDT does not validate whether the specified groups exist.
Fail
The Fail state indicates that the state machine did not execute correctly. This is an end state for the
state machine, and each state machine definition must include this state.
{
"Type": "Fail"
}
Succeed
The Succeed state indicates that the state machine executed correctly. This is an end state for the state
machine, and each state machine definition must include this state.
{
"Type": "Succeed"
}
State machine context
The state machine context is a read-only JSON document that contains data that is available to the state
machine during execution. The state machine context is accessible only from the state machine, and
contains information that determines the test flow. For example, you can use information configured by
test runners in the userdata.json file to determine whether a specific test is required to run.
The state machine context uses the following format:
{
"pool": {
<device-json-pool-element>
},
"userData": {
<userdata-json-content>
},
"config": {
<config-json-content>
871
AWS IoT Greengrass Developer Guide, Version 2
Configure the IDT state machine
},
"suiteFailed": true | false,
"specificTestGroups": [
"<group-id>"
],
"specificTestCases": [
"<test-id>"
],
"hasExecutionErrors": true
}
pool
Information about the device pool selected for the test run. For a selected device pool, this
information is retrieved from the corresponding top-level device pool array element defined in the
device.json file.
userData
Information in the userdata.json file.
config
Information pin the config.json file.
suiteFailed
The value is set to false when the state machine starts. If a test group fails in a RunTask state,
then this value is set to true for the remaining duration of the state machine execution.
specificTestGroups
If the test runner selects specific test groups to run instead of the entire test suite, this key is created
and contains the list of specific test group IDs.
specificTestCases
If the test runner selects specific test cases to run instead of the entire test suite, this key is created
and contains the list of specific test case IDs.
hasExecutionErrors
Does not exit when the state machine starts. If any state encounters an execution errors, this
variable is created and set to true for the remaining duration of the state machine execution.
You can query the context using JSONPath notation. The syntax for JSONPath queries in state definitions
is {{$.query}}. You can use JSONPath queries as placeholder strings within some states. IDT replaces
the placeholder strings with the value of the evaluated JSONPath query from the context. You can use
placeholders for the following values:
• The TestCases value in RunTask states.
• The Expression value Choice state.
When you access data from the state machine context, make sure the following conditions are met:
• Your JSON paths must begin with $.
• Each value must evaluate to a string, a number, or a boolean.
For more information about using JSONPath notation to access data from the context, see Use the IDT
context (p. 884).
872
AWS IoT Greengrass Developer Guide, Version 2
Configure the IDT state machine
Execution errors
Execution errors are errors in the state machine definition that the state machine encounters when
executing a state. IDT logs information about each error in the test_manager.log file and streams the
log message to the console.
You can use the following methods to handle execution errors:
• Add a Catch block (p. 873) in the state definition.
• Check the value of the hasExecutionErrors value (p. 873) in the state machine context.
Catch
To use Catch, add the following to your state definition:
"Catch": [
{
"ErrorEquals": [
"<error-type>"
]
"Next": "<state-name>"
}
]
All fields that contain values are required as described here:
Catch.ErrorEquals
An array of the error types to catch. If an execution error matches one of the specified values, then
the state machine transitions to the state specified in Catch.Next. See each state definition for
information about the type of error it produces.
Catch.Next
The next state to transition to if the current state encounters an execution error that matches one of
the values specified in Catch.ErrorEquals .
Catch blocks are handled sequentially until one matches. If the no errors match the ones listed in the
Catch blocks, then the state machines continues to execute. Because execution errors are a result of
incorrect state definitions, we recommend that you transition to the Fail state when a state encounters
an execution error.
hasExecutionError
When some states encounter execution errors, in addition to issuing the error, they also set the
hasExecutionError value to true in the state machine context. You can use this value to detect when
an error occurs, and then use a Choice state to transition the state machine to the Fail state.
This method has the following characteristics.
• The state machine does not start with any value assigned to hasExecutionError, and this
value is not available until a particular state sets it. This means that you must explicitly set the
FallthroughOnError to false for the Choice states that access this value to prevent the state
machine from stopping if no execution errors occur.
• Once it is set to true, hasExecutionError is never set to false or removed from the context. This
means that this value is useful only the first time that it is set to true, and for all subsequent states, it
does not provide a meaningful value.
873
AWS IoT Greengrass Developer Guide, Version 2
Configure the IDT state machine
• The hasExecutionError value is shared with all branch state machines in the Parallel state,
which can result in unexpected results depending on the order in which it is accessed.
Because of these characteristics, we do not recommend that you use this method if you can use a Catch
block instead.
Example state machines
This section provides some example state machine configurations.
Examples
• Example state machine: Run a single test group (p. 874)
• Example state machine: Run user-selected test groups (p. 875)
• Example state machine: Run a single test group with product features (p. 876)
• Example state machine: Run two test groups in parallel (p. 877)
Example state machine: Run a single test group
This state machine:
• Runs the test group with id GroupA, which must be present in the suite in a group.json file.
• Checks for execution errors and transitions to Fail if any are found.
• Generates a report and transitions to Succeed if there are no errors, and Fail otherwise.
{
"Comment": "Runs a single group and then generates a report.",
"StartAt": "RunGroupA",
"States": {
"RunGroupA": {
"Type": "RunTask",
"Next": "Report",
"TestGroup": "GroupA",
"Catch": [
{
"ErrorEquals": [
"RunTaskError"
],
"Next": "Fail"
}
]
},
"Report": {
"Type": "Report",
"Next": "Succeed",
"Catch": [
{
"ErrorEquals": [
"ReportError"
],
"Next": "Fail"
}
]
},
"Succeed": {
"Type": "Succeed"
},
"Fail": {
"Type": "Fail"
874
AWS IoT Greengrass Developer Guide, Version 2
Configure the IDT state machine
}
}
}
Example state machine: Run user-selected test groups
This state machine:
• Checks if the test runner selected specific test groups. The state machine does not check for specific
test cases because test runners cannot select test cases without also selecting a test group.
• If test groups are selected:
• Runs the test cases within the selected test groups. To do so, the state machine does not explicitly
specify any test groups or test cases in the RunTask state.
• Generates a report after running all tests and exits.
• If test groups are not selected:
• Runs tests in test group GroupA.
• Generates reports and exits.
{
"Comment": "Runs specific groups if the test runner chose to do that, otherwise runs
GroupA.",
"StartAt": "SpecificGroupsCheck",
"States": {
"SpecificGroupsCheck": {
"Type": "Choice",
"Default": "RunGroupA",
"FallthroughOnError": true,
"Choices": [
{
"Expression": "{{$.specificTestGroups[0]}} != ''",
"Next": "RunSpecificGroups"
}
]
},
"RunSpecificGroups": {
"Type": "RunTask",
"Next": "Report",
"Catch": [
{
"ErrorEquals": [
"RunTaskError"
],
"Next": "Fail"
}
]
},
"RunGroupA": {
"Type": "RunTask",
"Next": "Report",
"TestGroup": "GroupA",
"Catch": [
{
"ErrorEquals": [
"RunTaskError"
],
"Next": "Fail"
}
]
},
"Report": {
875
AWS IoT Greengrass Developer Guide, Version 2
Configure the IDT state machine
"Type": "Report",
"Next": "Succeed",
"Catch": [
{
"ErrorEquals": [
"ReportError"
],
"Next": "Fail"
}
]
},
"Succeed": {
"Type": "Succeed"
},
"Fail": {
"Type": "Fail"
}
}
}
Example state machine: Run a single test group with product features
This state machine:
• Runs the test group GroupA.
• Checks for execution errors and transitions to Fail if any are found.
• Adds the FeatureThatDependsOnGroupA feature to the awsiotdevicetester_report.xml file:
• If GroupA passes, the feature is set to supported.
• The feature is not marked optional in the report.
• Generates a report and transitions to Succeed if there are no errors, and Fail otherwise
{
"Comment": "Runs GroupA and adds product features based on GroupA",
"StartAt": "RunGroupA",
"States": {
"RunGroupA": {
"Type": "RunTask",
"Next": "AddProductFeatures",
"TestGroup": "GroupA",
"ResultVar": "GroupA_passed",
"Catch": [
{
"ErrorEquals": [
"RunTaskError"
],
"Next": "Fail"
}
]
},
"AddProductFeatures": {
"Type": "AddProductFeatures",
"Next": "Report",
"Features": [
{
"Feature": "FeatureThatDependsOnGroupA",
"Groups": [
"GroupA"
],
"IsRequired": true
}
]
876
AWS IoT Greengrass Developer Guide, Version 2
Configure the IDT state machine
},
"Report": {
"Type": "Report",
"Next": "Succeed",
"Catch": [
{
"ErrorEquals": [
"ReportError"
],
"Next": "Fail"
}
]
},
"Succeed": {
"Type": "Succeed"
},
"Fail": {
"Type": "Fail"
}
}
}
Example state machine: Run two test groups in parallel
This state machine:
• Runs the GroupA and GroupB test groups in parallel. The ResultVar variables stored in the context
by the RunTask states in the branch state machines by are available to the AddProductFeatures
state.
• Checks for execution errors and transitions to Fail if any are found. This state machine does not use a
Catch block because that method does not detect execution errors in branch state machines.
• Adds features to the awsiotdevicetester_report.xml file based on the groups that pass
• If GroupA passes, the feature is set to supported.
• The feature is not marked optional in the report.
• Generates a report and transitions to Succeed if there are no errors, and Fail otherwise
If two devices are configured in the device pool, both GroupA and GroupB can run at the same time.
However, if either GroupA or GroupB has multiple tests in it, then both devices may be allocated to
those tests. If only one device is configured, the test groups will run sequentially.
{
"Comment": "Runs GroupA and GroupB in parallel",
"StartAt": "RunGroupAAndB",
"States": {
"RunGroupAAndB": {
"Type": "Parallel",
"Next": "CheckForErrors",
"Branches": [
{
"Comment": "Run GroupA state machine",
"StartAt": "RunGroupA",
"States": {
"RunGroupA": {
"Type": "RunTask",
"Next": "Succeed",
"TestGroup": "GroupA",
"ResultVar": "GroupA_passed",
"Catch": [
{
"ErrorEquals": [
877
AWS IoT Greengrass Developer Guide, Version 2
Configure the IDT state machine
"RunTaskError"
],
"Next": "Fail"
}
]
},
"Succeed": {
"Type": "Succeed"
},
"Fail": {
"Type": "Fail"
}
}
},
{
"Comment": "Run GroupB state machine",
"StartAt": "RunGroupB",
"States": {
"RunGroupA": {
"Type": "RunTask",
"Next": "Succeed",
"TestGroup": "GroupB",
"ResultVar": "GroupB_passed",
"Catch": [
{
"ErrorEquals": [
"RunTaskError"
],
"Next": "Fail"
}
]
},
"Succeed": {
"Type": "Succeed"
},
"Fail": {
"Type": "Fail"
}
}
}
]
},
"CheckForErrors": {
"Type": "Choice",
"Default": "AddProductFeatures",
"FallthroughOnError": true,
"Choices": [
{
"Expression": "{{$.hasExecutionErrors}} == true",
"Next": "Fail"
}
]
},
"AddProductFeatures": {
"Type": "AddProductFeatures",
"Next": "Report",
"Features": [
{
"Feature": "FeatureThatDependsOnGroupA",
"Groups": [
"GroupA"
],
"IsRequired": true
},
{
"Feature": "FeatureThatDependsOnGroupB",
878
AWS IoT Greengrass Developer Guide, Version 2
Create IDT test case executables
"Groups": [
"GroupB"
],
"IsRequired": true
}
]
},
"Report": {
"Type": "Report",
"Next": "Succeed",
"Catch": [
{
"ErrorEquals": [
"ReportError"
],
"Next": "Fail"
}
]
},
"Succeed": {
"Type": "Succeed"
},
"Fail": {
"Type": "Fail"
}
}
}
Create IDT test case executables
You can create and place test case executables in a test suite folder in the following ways:
• For test suites that use arguments or environment variables from the test.json files to determine
which tests to run, you can create a single test case executable for the entire test suite, or a test
executable for each test group in the test suite.
• For a test suite where you want to run specific tests based on specified commands, you create one test
case executable for each test case in the test suite.
As a test writer, you can determine which approach is appropriate for your use case and structure your
test case executable accordingly. Make sure that your provide the correct test case executable path in
each test.json file, and that the specified executable runs correctly.
When all devices are ready for a test case to run, IDT reads the following files:
• The test.json for the selected test case determines the processes to start and the environment
variables to set.
• The suite.json for the test suite determines the environment variables to set.
IDT starts the required test exexutable process based on the commands and arguments specified in the
test.json file, and passes the required environment variables to the process.
Use the IDT Client SDK
The IDT Client SDKs let you simplify how you write test logic in your test executable with API commands
that you can use interact with IDT and your devices under test. IDT currently provides the following SDKs:
• IDT Client SDK for Python
• IDT Client SDK for Go
879
AWS IoT Greengrass Developer Guide, Version 2
Create IDT test case executables
These SDKs are located in the <device-tester-extract-location>/sdks folder. When you create
a new test case executable, you must copy the SDK that you want to use to the folder that contains your
test case executable and reference the SDK in your code. This section provides a brief description of the
available API commands that you can use in your test case executables.
In this section
• Device interaction (p. 880)
• IDT interaction (p. 880)
• Host interaction (p. 880)
Device interaction
The following commands enable you to communicate with the device under test without having to
implement any additional device interaction and connectivity management functions.
ExecuteOnDevice
Allows test suites to run shell commands on a device that support SSH or Docker shell connections.
CopyToDevice
Allows test suites to copy a local file from the host machine that runs IDT to a specified location on a
device that supports SSH or Docker shell connections.
ReadFromDevice
Allows test suites to read from the serial port of devices that support UART connections.
Note
Because IDT does not manage direct connections to devices that are made using device
access information from the context, we recommend using these device interaction API
commands in your test case executables. However, if these commands do not meet your test
case requirements, then you can retrieve device access information from the IDT context and use
it to make a direct connection to the device from the test suite.
To make a direct connection, retrieve the information in the device.connectivity and
the resource.devices.connectivity fields for your device under test and for resource
devices, respectively. For more information about using the IDT context, see Use the IDT
context (p. 884).
IDT interaction
The following commands enable your test suites to communicate with IDT.
PollForNotifications
Allows test suites to check for notifications from IDT.
GetContextValue and GetContextString
Allows test suites to retrieve values from the IDT context. For more information, see Use the IDT
context (p. 884).
SendResult
Allows test suites to report test case results to IDT. This command must be called at the end of each
test case in a test suite.
Host interaction
The following command enable your test suites to communicate with the host machine.
880
AWS IoT Greengrass Developer Guide, Version 2
Create IDT test case executables
PollForNotifications
Allows test suites to check for notifications from IDT.
GetContextValue and GetContextString
Allows test suites to retrieve values from the IDT context. For more information, see Use the IDT
context (p. 884).
ExecuteOnHost
Allows test suites to run commands on the local machine and lets IDT manage the test case
executable lifecycle.
Enable IDT CLI commands
The run-suite command IDT CLI provides several options that let test runner customize test execution.
To allow test runners to use these options to run your custom test suite, you implement support for the
IDT CLI. If you do not implement support, test runners will still be able to run tests, but some CLI options
will not function correctly. To provide an ideal customer experience, we recommend that you implement
support for the following arguments for the run-suite command in the IDT CLI:
timeout-multiplier
Specifies a value greater than 1.0 that will be applied to all timeouts while running tests.
Test runners can use this argument to increase the timeout for the test cases that they
want to run. When a test runner specifies this argument in their run-suite command, IDT
uses it to calculate the value of the IDT_TEST_TIMEOUT environment variable and sets the
config.timeoutMultiplier field in the IDT context. To support this argument, you must do the
following:
• Instead of directly using the timeout value from the test.json file, read the IDT_TEST_TIMEOUT
environment variable to obtain the correctly calculated timeout value.
• Retrieve the config.timeoutMultiplier value from the IDT context and apply it to long
running timeouts.
For more information about exiting early because of timeout events, see Specify exit
behavior (p. 883).
stop-on-first-failure
Specifies that IDT should stop running all tests if it encounters a failure.
When a test runner specifies this argument in their run-suite command, IDT will stop running
tests as soon as it encounters a failure. However, if test cases are running in parallel, then this
can lead to unexpected results. To implement support, make sure that if IDT encounters this
event, your test logic instructs all running test cases to stop, clean up temporary resources, and
report a test result to IDT. For more information about exiting early on failures, see Specify exit
behavior (p. 883).
group-id and test-id
Specifies that IDT should run only the selected test groups or test cases.
Test runners can use these arguments with their run-suite command to specify the following test
execution behavior:
• Run all tests inside the specified test groups.
• Run a selection of tests from within a specified test group.
To support these arguments, the state machine for your test suite must include a specific set of
RunTask and Choice states in your state machine. If you are not using a custom state machine,
then the default IDT state machine includes the required states for you and you do not need to
881
AWS IoT Greengrass Developer Guide, Version 2
Create IDT test case executables
take additional action. However, if you are using a custom state machine, then use Example state
machine: Run user-selected test groups (p. 875) as a sample to add the required states in your
state machine.
For more information about IDT CLI commands, see Debug and run custom test suites (p. 894).
Write event logs
While the test is running, you send data to stdout and stderr to write event logs and error
messages to the console. For information about the format of console messages, see Console message
format (p. 896).
When the IDT finishes running the test suite, this information is also available in the
test_manager.log file located in the <devicetester-extract-location>/
results/<execution-id>/logs folder.
You can configure each test case to write the logs from its test run, including logs from the device under
test, to the <group-id>_<test-id> file located in the <device-tester-extract-location>/
results/execution-id/logs folder. To do this, retrieve the path to the log file from the IDT context
with the testData.logFilePath query, create a file at that path, and write the content that you want
to it. IDT automatically updates the path based on the test case that is running. If you choose not to
create the log file for a test case, then no file is generated for that test case.
You can also set up your text executable to create additional log files as needed in the <device-
tester-extract-location>/logs folder. We recommend that you specify unique prefixes for log file
names so your files don't get overwritten.
Report results to IDT
IDT writes test results to the awsiotdevicetester_report.xml and the suite-
name_report.xml files. These report files are located in <device-tester-extract-location>/
results/<execution-id>/. Both reports capture the results from the test suite execution. For
more information about the schemas that IDT uses for these reports, see Review IDT test results and
logs (p. 896)
To populate the contents of the suite-name_report.xml file, you must use the SendResult
command to report test results to IDT before the test execution finishes. If IDT cannot locate the results
of a test, it issues an error for the test case. The following Python excerpt shows the commands to send a
test result to IDT:
request-variable = SendResultRequest(TestResult(result))
client.send_result(request-variable)
If you do not report results through the API, IDT looks for test results in the test artifacts folder. The path
to this folder is stored in the testData.testArtifactsPath filed in the IDT context. In this folder, IDT
uses the first alphabetically sorted XML file it locates as the test result.
If your test logic produces JUnit XML results, you can write the test results to an XML file in the artifacts
folder to directly provide the results to IDT instead of parsing the results and then using the API to
submit them to IDT.
If you use this method, make sure that your test logic accurately summarizes the test results and format
your result file in the same format as the suite-name_report.xml file. IDT does not perform any
validation of the data that you provide, with the following exceptions:
• IDT ignores all properties of the testsuites tag. Instead, it calculates the tag properties from other
reported test group results.
• At least one testsuite tag must exist within testsuites.
882
AWS IoT Greengrass Developer Guide, Version 2
Create IDT test case executables
Because IDT uses the same artifacts folder for all test cases and does not delete result files between test
runs, this method might also lead to erroneous reporting if IDT reads the incorrect file. We recommend
that you use the same name for the generated XML results file across all test cases to overwrite the
results for each test case and make sure that the correct results are available for IDT to use. Although
you can use a mixed approach to reporting in your test suite, that is, use an XML result file for some test
cases and submit results through the API for others, we do not recommend this approach.
Specify exit behavior
Configure your text executable to always exit with an exit code of 0, even if a test case reports a failure
or an error result. Use non-zero exit codes only to indicate that a test case did not run or if the test case
executable could not communicate any results to IDT. When IDT receives a non-zero exit code, it marks
the test case has having encountered an error that prevented it from running.
IDT might request or expect a test case to stop running before it has finished in the following events. Use
this information to configure your test case executable to detect each of these events from the test case:
Timeout
Occurs when a test case runs for longer than the timeout value specified in the test.json file. If
the test runner used the timeout-multiplier argument to specify a timeout multiplier, then IDT
calculates the timeout value with the multiplier.
To detect this event, use the IDT_TEST_TIMEOUT environment variable. When a test runner launches
a test, IDT sets the value of the IDT_TEST_TIMEOUT environment variable to the calculated timeout
value (in seconds) and passes the variable to the test case executable. You can read the variable
value to set an appropriate timer.
Interrupt
Occurs when the test runner interrupts IDT. For example, by pressing Ctrl+C.
Because terminals propagate signals to all child processes, you can simply configure a signal handler
in your test cases to detect interrupt signals.
Alternatively, you can periodically poll the API to check the value of the CancellationRequested
boolean in the PollForNotifications API response. When IDT receives an interrupt signal, it sets
the value of the CancellationRequested boolean to true.
Stop on first failure
Occurs when a test case that is running in parallel with the current test case fails and the test runner
used the stop-on-first-failure argument to specify that IDT should stop when it encounters
any failure.
To detect this event, you can periodically poll the API to check the value of the
CancellationRequested boolean in the PollForNotifications API response. When
IDT encounters a failure and is configured to stop on first failure, it sets the value of the
CancellationRequested boolean to true.
When any of these events occur, IDT waits for 5 minutes for any currently running test cases to finish
running. If all running test cases do not exit within 5 minutes, IDT forces each of their processes to stop.
If IDT has not received test results before the processes end, it will mark the test cases as having timed
out. As a best practice, you should ensure that your test cases perform the following actions when they
encounter one of the events:
1. Stop running normal test logic.
2. Clean up any temporary resources, such as test artifacts on the device under test.
3. Report a test result to IDT, such as a test failure or an error.
4. Exit.
883
AWS IoT Greengrass Developer Guide, Version 2
Use the IDT context
Use the IDT context
When IDT runs a test suite, the test suite can access a set of data that can be used to determine how
each test runs. This data is called the IDT context. For example, user data configuration provided by test
runners in a userdata.json file is made available to test suites in the IDT context.
The IDT context can be considered a read-only JSON document. Test suites can retrieve data from and
write data to the context using standard JSON data types like objects, arrays, numbers and so on.
Context schema
The IDT context uses the following format:
{
"config": {
<config-json-content>
"timeoutMultiplier": timeout-multiplier
},
"device": {
<device-json-device-element>
},
"devicePool": {
<device-json-pool-element>
},
"resource": {
"devices": [
{
<resource-json-device-element>
"name": "<resource-name>"
}
]
},
"testData": {
"awsCredentials": {
"awsAccessKeyId": "<access-key-id>",
"awsSecretAccessKey": "<secret-access-key>",
"awsSessionToken": "<session-token>"
},
"logFilePath": "/path/to/log/file"
},
"userData": {
<userdata-json-content>
}
}
config
Information from the config.json file (p. 892). The config field also contains the following
additional field:
config.timeoutMultiplier
The multiplier for the any timeout value used by the test suite. This value is specified by the test
runner from the IDT CLI. The default value is 1.
device
Information about the device selected for the test run. This information is equivalent to the
devices array element in the device.json file (p. 887) for the selected device.
devicePool
Information about the device pool selected for the test run. This information is equivalent to the
top-level device pool array element defined in the device.json file for the selected device pool.
884
AWS IoT Greengrass Developer Guide, Version 2
Use the IDT context
resource
Information about resource devices from the resource.json file.
resource.devices
This information is equivalent to the devices array defined in the resource.json file. Each
devices element includes the following additional field:
resource.device.name
The name of the resource device. This value is set to the requiredResource.name value
in the test.json file.
testData.awsCredentials
The AWS credentials used by the test to connect to the AWS cloud. This information is obtained
from the config.json file.
testData.logFilePath
The path to the log file to which the test case writes log messages. The test suite creates this file if it
doesn't exist.
userData
Information provided by the test runner in the userdata.json file (p. 890).
Access data in the context
You can query the context using JSONPath notation from your JSON files and from your text executable
with the GetContextValue and GetContextString APIs. The syntax for JSONPath strings to access
the IDT context varies as follows:
• In suite.json and test.json, you use {{query}}. That is, do not use the root element $. to start
your expression.
• In statemachine.json, you use {{$.query}}.
• In API commands, you use query or {{$.query}}, depending on the command. For more
information, see the inline documentation in the SDKs.
The following table describes the operators in a typical JSONPath expression:
Operator Description
$ The root element. Because the top-level context
value for IDT is an object, you will typically use $.
to start your queries.
.childName Accesses the child element with name childName
from an object. If applied to an array, yields a new
array with this operator applied to each element.
The element name is case sensitive. For example,
the query to access the awsRegion value in the
config object is $.config.awsRegion.
[start:end] Filters elements from an array, retrieving items
beginning from the start index and going up to
the end index, both inclusive.
[index1, index2, ... , indexN] Filters elements from an array, retrieving items
from only the specified indices.
885
AWS IoT Greengrass Developer Guide, Version 2
Configure settings for test runners
Operator Description
[?(expr)] Filters elements from an array using the expr
expression. This expression must evaluate to a
boolean value.
To create filter expressions, use the following syntax:
<jsonpath> | <value> operator <jsonpath> | <value>
In this syntax:
• jsonpath is a JSONPath that uses standard JSON syntax.
• value is any custom value that uses standard JSON syntax.
• operator is one of the following operators:
• < (Less than)
• <= (Less than or equal to)
• == (Equal to)
If the JSONPath or value in your expression is an array, boolean, or object value, then this is the only
supported binary operator that you can use.
• >= (Greater than or equal to)
• > (Greater than)
• =~ (Regular expression match). To use this operator in a filter expression, the JSONPath or value on
the left side of your expression must evaluate to a string and the right side must be a pattern value
that follows the RE2 syntax.
You can use JSONPath queries in the form {{query}} as placeholder strings within the args and
environmentVariables fields in test.json files and within the environmentVariables fields in
suite.json files. IDT performs a context lookup and populates the fields with the evaluated value of
the query. For example, in the suite.json file, you can use placeholder strings to specify environment
variable values that change with each test case and IDT will populate the environment variables with
the correct value for each test case. However, when you use placeholder strings in test.json and
suite.json files, the following considerations apply for your queries:
• You must each occurrence of the devicePool key in your query in all lower case. That is, use
devicepool instead.
• For arrays, you can use only arrays of strings. In addition, arrays use a non-standard item1,
item2,...,itemN format. If the array contains only one element, then it is serialized as item,
making it indistinguishable from a string field.
• You cannot use placeholders to retrieve objects from the context.
Because of these considerations, we recommend that whenever possible, you use the API to access the
context in your test logic instead of placeholder strings in test.json and suite.json files. However,
in some cases it might be more convenient to use JSONPath placeholders to retrieve single strings to set
as environment variables.
Configure settings for test runners
To run custom test suites, test runners must configure their settings based on the test suite that they
want to run. Settings are specified based on JSON configuration file templates located in the <device-
886
AWS IoT Greengrass Developer Guide, Version 2
Configure settings for test runners
tester-extract-location>/configs/ folder. If required, test runners must also set up AWS
credentials that IDT will use to connect to the AWS cloud.
As a test writer, you will need to configure these files to debug your test suite (p. 894). You must
provide instructions to test runners so that they can configure the following settings as needed to run
your test suites.
Configure device.json
The device.json file contains information about the devices that tests are run on (for example, IP
address, login information, operating system, and CPU architecture).
Test runners can provide this information using the following template device.json file located in the
<device-tester-extract-location>/configs/ folder.
[
{
"id": "<pool-id>",
"sku": "<pool-sku>",
"features": [
{
"name": "<feature-name>",
"value": "<feature-value>",
"configs": [
{
"name": "<config-name>",
"value": "<config-value>"
}
],
}
],
"devices": [
{
"id": "<device-id>",
"connectivity": {
"protocol": "ssh | uart | docker",
// ssh
"ip": "<ip-address>",
"port": <port-number>,
"auth": {
"method": "pki | password",
"credentials": {
"user": "<user-name>",
// pki
"privKeyPath": "/path/to/private/key",
// password
"password": "<password>",
}
},
// uart
"serialPort": "<serial-port>",
// docker
"containerId": "<container-id>",
"containerUser": "<container-user-name>",
}
}
]
}
]
887
AWS IoT Greengrass Developer Guide, Version 2
Configure settings for test runners
All fields that contain values are required as described here:
id
A user-defined alphanumeric ID that uniquely identifies a collection of devices called a device pool.
Devices that belong to a pool must have identical hardware. When you run a suite of tests, devices in
the pool are used to parallelize the workload. Multiple devices are used to run different tests.
sku
An alphanumeric value that uniquely identifies the device under test. The SKU is used to track
qualified devices.
Note
If you want to list your board in the AWS Partner Device Catalog, the SKU you specify here
must match the SKU that you use in the listing process.
features
Optional. An array that contains the device's supported features. Device features are user-defined
values that you configure in your test suite. You must provide your test runners with information
about the feature names and values to include in the device.json file. For example, if you want
to test a device that functions as an MQTT server for other devices, then you can configure your test
logic to validate specific supported levels for a feature named MQTT_QOS. Test runners provide this
feature name and set the feature value to the QOS levels supported by their device. You can retrieve
the provided information from the IDT context (p. 884) with the devicePool.features query, or
from the state machine context (p. 871) with the pool.features query.
features.name
The name of the feature.
features.value
The supported feature values.
features.configs
Configuration settings, if needed, for the feature.
features.config.name
The name of the configuration setting.
features.config.value
The supported setting values.
devices
An array of devices in the pool to be tested. At least one device is required.
devices.id
A user-defined unique identifier for the device being tested.
connectivity.protocol
The communication protocol used to communicate with this device. Each device in a pool must
use the same protocol.
Currently, the only supported values are ssh and uart for physical devices, and docker for
Docker containers.
connectivity.ip
The IP address of the device being tested.
This property applies only if connectivity.protocol is set to ssh.
888
AWS IoT Greengrass Developer Guide, Version 2
Configure settings for test runners
connectivity.port
Optional. The port number to use for SSH connections.
The default value is 22.
This property applies only if connectivity.protocol is set to ssh.
connectivity.auth
Authentication information for the connection.
This property applies only if connectivity.protocol is set to ssh.
connectivity.auth.method
The authentication method used to access a device over the given connectivity protocol.
Supported values are:
• pki
• password
connectivity.auth.credentials
The credentials used for authentication.
connectivity.auth.credentials.password
The password used for signing in to the device being tested.
This value applies only if connectivity.auth.method is set to password.
connectivity.auth.credentials.privKeyPath
The full path to the private key used to sign in to the device under test.
This value applies only if connectivity.auth.method is set to pki.
connectivity.auth.credentials.user
The user name for signing in to the device being tested.
connectivity.serialPort
Optional. The serial port to which the device is connected.
This property applies only if connectivity.protocol is set to uart.
connectivity.containerId
The container ID or name of the Docker container being tested.
This property applies only if connectivity.protocol is set to ssh.
connectivity.containerUser
Optional. The name of the user to user inside the container. The default value is the user
provided in the Dockerfile.
The default value is 22.
This property applies only if connectivity.protocol is set to ssh.
Note
To check if test runners configure the incorrect device connection for a test, you can retrieve
pool.Devices[0].Connectivity.Protocol from the state machine context and
compare it to the expected value in a Choice state. If an incorrect protocol is used, then
print a message using the LogMessage state and transition to the Fail state.
Alternatively, you can use error handling code to report a test failure for incorrect device
types.
889
AWS IoT Greengrass Developer Guide, Version 2
Configure settings for test runners
(Optional) Configure userdata.json
The userdata.json file contains any additional information that is required by a test suite but is not
specified in the device.json file. The format of this file depends on the userdata_scheme.json
file (p. 863) that is defined in the test suite. If you are a test writer, make sure you provide this
information to users who will run the test suites that you write.
(Optional) Configure resource.json
The resource.json file contains information about any devices that will be used as resource devices.
Resource devices are devices that are required to test certain capabilities of a device under test. For
example, to test a device's Bluetooth capability, you might use a resource device to test that your device
can connect to it successfully. Resource devices are optional, and you can require as many resources
devices as you need. As a test writer, you use the test.json file (p. 860) to define the resource device
features that are required for a test. Test runners then use the resource.json file to provide a pool of
resource devices that have the required features. Make sure you provide this information to users who
will run the test suites that you write.
Test runners can provide this information using the following template resource.json file located in
the <device-tester-extract-location>/configs/ folder.
[
{
"id": "<pool-id>",
"features": [
{
"name": "<feature-name>",
"version": "<feature-version>",
"jobSlots": <job-slots>
}
],
"devices": [
{
"id": "<device-id>",
"connectivity": {
"protocol": "ssh | uart | docker",
// ssh
"ip": "<ip-address>",
"port": <port-number>,
"auth": {
"method": "pki | password",
"credentials": {
"user": "<user-name>",
// pki
"privKeyPath": "/path/to/private/key",
// password
"password": "<password>",
}
},
// uart
"serialPort": "<serial-port>",
// docker
"containerId": "<container-id>",
"containerUser": "<container-user-name>",
}
}
]
}
]
890
AWS IoT Greengrass Developer Guide, Version 2
Configure settings for test runners
All fields that contain values are required as described here:
id
A user-defined alphanumeric ID that uniquely identifies a collection of devices called a device pool.
Devices that belong to a pool must have identical hardware. When you run a suite of tests, devices in
the pool are used to parallelize the workload. Multiple devices are used to run different tests.
features
Optional. An array that contains the device's supported features. The information required in this
field is defined in the test.json files (p. 860) in the test suite and determines which tests to run and
how to run those tests. If the test suite does not require any features, then this field is not required.
features.name
The name of the feature.
features.version
The feature version.
features.jobSlots
Setting to indicate how many tests can concurrently use the device. The default value is 1.
devices
An array of devices in the pool to be tested. At least one device is required.
devices.id
A user-defined unique identifier for the device being tested.
connectivity.protocol
The communication protocol used to communicate with this device. Each device in a pool must
use the same protocol.
Currently, the only supported values are ssh and uart for physical devices, and docker for
Docker containers.
connectivity.ip
The IP address of the device being tested.
This property applies only if connectivity.protocol is set to ssh.
connectivity.port
Optional. The port number to use for SSH connections.
The default value is 22.
This property applies only if connectivity.protocol is set to ssh.
connectivity.auth
Authentication information for the connection.
This property applies only if connectivity.protocol is set to ssh.
connectivity.auth.method
The authentication method used to access a device over the given connectivity protocol.
Supported values are:
• pki
• password
891
AWS IoT Greengrass Developer Guide, Version 2
Configure settings for test runners
connectivity.auth.credentials
The credentials used for authentication.
connectivity.auth.credentials.password
The password used for signing in to the device being tested.
This value applies only if connectivity.auth.method is set to password.
connectivity.auth.credentials.privKeyPath
The full path to the private key used to sign in to the device under test.
This value applies only if connectivity.auth.method is set to pki.
connectivity.auth.credentials.user
The user name for signing in to the device being tested.
connectivity.serialPort
Optional. The serial port to which the device is connected.
This property applies only if connectivity.protocol is set to uart.
connectivity.containerId
The container ID or name of the Docker container being tested.
This property applies only if connectivity.protocol is set to ssh.
connectivity.containerUser
Optional. The name of the user to user inside the container. The default value is the user
provided in the Dockerfile.
The default value is 22.
This property applies only if connectivity.protocol is set to ssh.
(Optional) Configure config.json
The config.json file contains configuration information for IDT. Typically, test runners will not need
to modify this file except to provide their AWS user credentials for IDT, and optionally, an AWS region.
If AWS credentials with required permissions are provided AWS IoT Device Tester collects and submits
usage metrics to AWS. This is an opt-in feature and is used to improve IDT functionality. For more
information, see IDT usage metrics (p. 900).
Test runners can configure their AWS credentials in one of the following ways:
• Credentials file
IDT uses the same credentials file as the AWS CLI. For more information, see Configuration and
credential files.
The location of the credentials file varies, depending on the operating system you are using:
• macOS, Linux: ~/.aws/credentials
• Windows: C:\Users\UserName\.aws\credentials
• Environment variables
Environment variables are variables maintained by the operating system and used by system
commands. Variables defined during an SSH session are not available after that session is closed. IDT
can use the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables to store
AWS credentials
892
AWS IoT Greengrass Developer Guide, Version 2
Configure settings for test runners
To set these variables on Linux, macOS, or Unix, use export:
export AWS_ACCESS_KEY_ID=<your_access_key_id>
export AWS_SECRET_ACCESS_KEY=<your_secret_access_key>
To set these variables on Windows, use set:
set AWS_ACCESS_KEY_ID=<your_access_key_id>
set AWS_SECRET_ACCESS_KEY=<your_secret_access_key>
To configure AWS credentials for IDT, test runners edit the auth section in the config.json file located
in the <device-tester-extract-location>/configs/ folder.
{
"log": {
"location": "logs"
},
"configFiles": {
"root": "configs",
"device": "configs/device.json"
},
"testPath": "tests",
"reportPath": "results",
"awsRegion": "<region>",
"auth": {
"method": "file | environment",
"credentials": {
"profile": "<profile-name>"
}
}
}
]
All fields that contain values are required as described here:
Note
All paths in this file are defined relative to the <device-tester-extract-location>.
log.location
The path to the logs folder in the <device-tester-extract-location>.
configFiles.root
The path to the folder that contains the configuration files.
configFiles.device
The path to the device.json file.
testPath
The path to the folder that contains test suites.
reportPath
The path to the folder that will contain test results after IDT runs a test suite.
awsRegion
Optional. The AWS region that test suites will use. If not set, then test suites will use the default
region specified in each test suite.
893
AWS IoT Greengrass Developer Guide, Version 2
Debug and run custom test suites
auth.method
The method IDT uses to retrieve AWS credentials. Supported values are file to retrieve credentials
from a credentials file, and environment to retrieve credentials using environment variables.
auth.credentials.profile
The credentials profile to use from the credentials file. This property applies only if auth.method is
set to file.
Debug and run custom test suites
After the required configuration (p. 886) is set, IDT can run your test suite. The runtime of the full
test suite depends on the hardware and the composition of the test suite. For reference, it takes
approximately 30 minutes to complete the full AWS IoT Greengrass qualification test suite on a
Raspberry Pi 3B.
As you write your test suite, you can use IDT to run the test suite in debug mode to check your code
before you run it or provide it to test runners.
Run IDT in debug mode
Because test suites depend on IDT to interact with devices, provide the context, and receive results, you
cannot simply debug your test suites in an IDE without any IDT interaction. To do so, the IDT CLI provides
the debug-test-suite command that lets you run IDT in debug mode. Run the following command to
view the available options for debug-test-suite:
devicetester_[linux | mac | win_x86-64] debug-test-suite -h
When you run IDT in debug mode, IDT does not actually launch the test suite or run the state machine;
instead, it interacts with your IDE to responds to requests made from the test suite running in the IDE
and prints the logs to the console. IDT does not time out and waits to exit until manually interrupted. In
debug mode, IDT also does not run the state machine and will not generate any report files. To debug
your test suite, you must use your IDE to provide some information that IDT usually obtains from the
configuration JSON files. Make sure you provide the following information:
• Environment variables and arguments for each test. IDT will not read this information from
test.json or suite.json.
• Arguments to select resource devices. IDT will not read this information from test.json.
To debug your test suites, complete the following steps:
1. Create the setting configuration files that are required to run the test suite. For example, if your test
suite requires the device.json, resource.json, and user data.json, make sure you configure
all of them as needed.
2. Run the following command to place IDT in debug mode and select any devices that are required to
run the test.
devicetester_[linux | mac | win_x86-64] debug-test-suite [options]
After you run this command, IDT waits for requests from the test suite and then responds to them.
IDT also generates the environment variables that are required for the case process for the IDT Client
SDK.
3. In your IDE, use the run or debug configuration to do the following:
894
AWS IoT Greengrass Developer Guide, Version 2
Debug and run custom test suites
a. Set the values of the IDT-generated environment variables.
b. Set the value of any environment variables or arguments that you specified in your test.json
and suite.json file.
c. Set breakpoints as needed.
4. Run the test suite in your IDE.
You can debug and re-run the test suite as many times as needed. IDT does not time out in debug
mode.
5. After you complete debugging, interrupt IDT to exit debug mode.
IDT CLI commands to run tests
The following section describes the IDT CLI commands:
IDT v4.0.0
help
Lists information about the specified command.
list-groups
Lists the groups in a given test suite.
list-suites
Lists the available test suites.
list-supported-products
Lists the supported products for your version of IDT, in this case AWS IoT Greengrass versions,
and AWS IoT Greengrass qualification test suite versions available for the current IDT version.
list-test-cases
Lists the test cases in a given test group. The following option is supported:
• group-id. The test group to search for. This option is required and must specify a single
group.
run-suite
Runs a suite of tests on a pool of devices. The following are some commonly used options:
• suite-id. The test suite version to run. If not specified, IDT uses the latest version in the
tests folder.
• group-id. The test groups to run, as a comma-separated list. If not specified, IDT runs all test
groups in the test suite.
• test-id. The test cases to run, as a comma-separated list. When specified, group-id must
specify a single group.
• pool-id. The device pool to test. Test runners must specify a pool if they have multiple
device pools defined in your device.json file.
• timeout-multiplier. Configures IDT to modify the test execution timeout specified in the
test.json file for a test with a user-defined multiplier.
• stop-on-first-failure. Configures IDT to stop execution on the first failure. This option
should be used with group-id to debug the specified test groups.
• userdata. Sets the file that contains user data information required to run the test suite. This
is required only if userdataRequired is set to true in the suite.json file for the test suite.
895
AWS IoT Greengrass Developer Guide, Version 2
Review IDT test results and logs
For more information about run-suite options, use the help option:
devicetester_[linux | mac | win_x86-64] run-suite -h
debug-test-suite
Run the test suite in debug mode. For more information, see Run IDT in debug mode (p. 894).
Review IDT test results and logs
This section describes the format in which IDT generates console logs and test reports.
Console message format
AWS IoT Device Tester uses a standard format for printing messages to the console when it starts a test
suite. The following excerpt shows an example of a console message generated by IDT.
time="2000-01-02T03:04:05-07:00" level=info msg=Using suite: MyTestSuite_1.0.0
executionId=9a52f362-1227-11eb-86c9-8c8590419f30
Most console messages consist of the following fields:
time
A full ISO 8601 timestamp for the logged event.
level
The message level for the logged event. Typically, the logged message level is one of info, warn, or
error. IDT issues a fatal or panic message if it encounters an expected event that causes it to exit
early.
msg
The logged message.
executionId
A unique ID string for the current IDT process. This ID is used to differentiate between individual IDT
runs.
Console messages generated from a test suite provide additional information about the device under
test and the test suite, test group, and test cases that IDT runs. The following excerpt shows an example
of a console message generated from a test suite.
time="2000-01-02T03:04:05-07:00" level=info msg=Hello world! suiteId=MyTestSuite
groupId=myTestGroup testCaseId=myTestCase deviceId=my-device
executionId=9a52f362-1227-11eb-86c9-8c8590419f30
The test-suite specific part of the console message contains the following fields:
suiteId
The name of the test suite currently running.
groupId
The ID of the test group currently running.
896
AWS IoT Greengrass Developer Guide, Version 2
Review IDT test results and logs
testCaseId
The ID of the test case current running.
deviceId
A ID of the device under test that the current test case is using.
To print a test summary to the console when a IDT finishes running a test, you must include a Report
state (p. 870) in your state machine. The test summary contains information about the test suite, the
test results for each group that was run, and the locations of the generated logs and report files. The
following example shows a test summary message.
========== Test Summary ==========
Execution Time: 5m00s
Tests Completed: 4
Tests Passed: 3
Tests Failed: 1
Tests Skipped: 0
----------------------------------
Test Groups:
GroupA: PASSED
GroupB: FAILED
----------------------------------
Failed Tests:
Group Name: GroupB
Test Name: TestB1
Reason: Something bad happened
----------------------------------
Path to IoT Device Tester Report: /path/to/awsiotdevicetester_report.xml
Path to Test Execution Logs: /path/to/logs
Path to Aggregated JUnit Report: /path/to/MyTestSuite_Report.xml
AWS IoT Device Tester report schema
awsiotdevicetester_report.xml is a signed report that contains the following information:
• The IDT version.
• The test suite version.
• The report signature and key used to sign the report.
• The device SKU and the device pool name specified in the device.json file.
• The product version and the device features that were tested.
• The aggregate summary of test results. This information is the same as that contained in the suite-
name_report.xml file.
<apnreport>
<awsiotdevicetesterversion>idt-version</awsiotdevicetesterversion>
<testsuiteversion>test-suite-version</testsuiteversion>
<signature>signature</signature>
<keyname>keyname</keyname>
<session>
<testsession>execution-id</testsession>
<starttime>start-time</starttime>
<endtime>end-time</endtime>
</session>
<awsproduct>
<name>product-name</name>
<version>product-version</version>
897
AWS IoT Greengrass Developer Guide, Version 2
Review IDT test results and logs
<features>
<feature name="<feature-name>" value="supported | not-supported | <feature-
value>" type="optional | required"/>
</features>
</awsproduct>
<device>
<sku>device-sku</sku>
<name>device-name</name>
<features>
<feature name="<feature-name>" value="<feature-value>"/>
</features>
<executionMethod>ssh | uart | docker</executionMethod>
</device>
<devenvironment>
<os name="<os-name>"/>
</devenvironment>
<report>
<suite-name-report-contents>
</report>
</apnreport>
The awsiotdevicetester_report.xml file contains an <awsproduct> tag that contains information
about the product being tested and the product features that were validated after running a suite of
tests.
Attributes used in the <awsproduct> tag
name
The name of the product being tested.
version
The version of the product being tested.
features
The features validated. Features marked as required are required for the test suite to
validate the device. The following snippet shows how this information appears in the
awsiotdevicetester_report.xml file.
<feature name="ssh" value="supported" type="required"></feature>
Features marked as optional are not required for validation. The following snippets show optional
features.
<feature name="hsi" value="supported" type="optional"></feature>
<feature name="mqtt" value="not-supported" type="optional"></feature>
Test suite report schema
The suite-name_Result.xml report is in JUnit XML format. You can integrate it into continuous
integration and deployment platforms like Jenkins, Bamboo, and so on. The report contains an
aggregate summary of test results.
<testsuites name="<suite-name> results" time="<run-duration>" tests="<number-of-test>"
failures="<number-of-tests>" skipped="<number-of-tests>" errors="<number-of-tests>"
disabled="0">
898
AWS IoT Greengrass Developer Guide, Version 2
Review IDT test results and logs
<testsuite name="<test-group-id>" package="" tests="<number-of-tests>"
failures="<number-of-tests>" skipped="<number-of-tests>" errors="<number-of-tests>"
disabled="0">
<!--success-->
<testcase classname="<classname>" name="<name>" time="<run-duration>"/>
<!--failure-->
<testcase classname="<classname>" name="<name>" time="<run-duration>">
<failure type="<failure-type>">
reason
</failure>
</testcase>
<!--skipped-->
<testcase classname="<classname>" name="<name>" time="<run-duration>">
<skipped>
reason
</skipped>
</testcase>
<!--error-->
<testcase classname="<classname>" name="<name>" time="<run-duration>">
<error>
reason
</error>
</testcase>
</testsuite>
</testsuites>
The report section in both the awsiotdevicetester_report.xml or suite-name_report.xml lists
the tests that were run and the results.
The first XML tag <testsuites> contains the summary of the test execution. For example:
<testsuites name="MyTestSuite results" time="2299" tests="28" failures="0" errors="0"
disabled="0">
Attributes used in the <testsuites> tag
name
The name of the test suite.
time
The time, in seconds, it took to run the test suite.
tests
The number of tests executed.
failures
The number of tests that were run, but did not pass.
errors
The number of tests that IDT couldn't execute.
disabled
This attribute is not used and can be ignored.
In the event of test failures or errors, you can identify the test that failed by reviewing the
<testsuites> XML tags. The <testsuite> XML tags inside the <testsuites> tag show the test
result summary for a test group. For example:
899
AWS IoT Greengrass Developer Guide, Version 2
IDT usage metrics
<testsuite name="combination" package="" tests="1" failures="0" time="161" disabled="0"
errors="0" skipped="0">
The format is similar to the <testsuites> tag, but with a skipped attribute that is not used and can
be ignored. Inside each <testsuite> XML tag, there are <testcase> tags for each executed test for a
test group. For example:
<testcase classname="Security Test" name="IP Change Tests" attempts="1"></testcase>>
Attributes used in the <testcase> tag
name
The name of the test.
attempts
The number of times IDT executed the test case.
When a test fails or an error occurs, <failure> or <error> tags are added to the <testcase> tag with
information for troubleshooting. For example:
<testcase classname="mcu.Full_MQTT" name="MQTT_TestCase" attempts="1">
<failure type="Failure">Reason for the test failure</failure>
<error>Reason for the test execution error</error>
</testcase>
IDT usage metrics
If you provide AWS credentials with required permissions, AWS IoT Device Tester collects and submits
usage metrics to AWS. This is an opt-in feature and is used to improve IDT functionality. IDT collects
information such as the following:
• The AWS account ID used to run IDT
• The IDT CLI commands used to run tests
• The test suite that are run
• The test suites in the <device-tester-extract-location> folder
• The number of devices configured in the device pool
• Test case names and run times
• Test result information, such as whether tests passed, failed, encountered errors, or were skipped
• Product features tested
• IDT exit behavior, such as unexpected or early exits
All of the information that IDT sends is also logged to a metrics.log file in the <device-tester-
extract-location>/results/<execution-id>/ folder. You can view the log file to see the
information that was collected during a test run. This file is generated only if you choose to collect usage
metrics.
To disable metrics collection, you do not need to take additional action. Simply do not store your AWS
credentials, and if you do have stored AWS credentials, do not configure the config.json file to access
them.
900
AWS IoT Greengrass Developer Guide, Version 2
IDT usage metrics
Configure your AWS credentials
If you do not already have an AWS account, you must create one (p. 901). If you already have an AWS
account, you simply need to configure the required permissions (p. 902) for your account that allow IDT
to send usage metrics to AWS on your behalf.
Step 1: Create an AWS account
In this step, create and configure an AWS account. If you already have an AWS account, skip to the
section called “Step 2: Configure permissions for IDT” (p. 902).
If you do not have an AWS account, complete the following steps to create one.
To sign up for an AWS account
1. Open https://portal.aws.amazon.com/billing/signup.
2. Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call and entering a verification code on the
phone keypad.
To create an administrator user for yourself and add the user to an administrators group
(console)
1. Sign in to the IAM console as the account owner by choosing Root user and entering your AWS
account email address. On the next page, enter your password.
Note
We strongly recommend that you adhere to the best practice of using the Administrator
IAM user that follows and securely lock away the root user credentials. Sign in as the root
user only to perform a few account and service management tasks.
2. In the navigation pane, choose Users and then choose Add user.
3. For User name, enter Administrator.
4. Select the check box next to AWS Management Console access. Then select Custom password, and
then enter your new password in the text box.
5. (Optional) By default, AWS requires the new user to create a new password when first signing in. You
can clear the check box next to User must create a new password at next sign-in to allow the new
user to reset their password after they sign in.
6. Choose Next: Permissions.
7. Under Set permissions, choose Add user to group.
8. Choose Create group.
9. In the Create group dialog box, for Group name enter Administrators.
10. Choose Filter policies, and then select AWS managed - job function to filter the table contents.
11. In the policy list, select the check box for AdministratorAccess. Then choose Create group.
Note
You must activate IAM user and role access to Billing before you can use the
AdministratorAccess permissions to access the AWS Billing and Cost Management
console. To do this, follow the instructions in step 1 of the tutorial about delegating access
to the billing console.
12. Back in the list of groups, select the check box for your new group. Choose Refresh if necessary to
see the group in the list.
901
AWS IoT Greengrass Developer Guide, Version 2
IDT usage metrics
13. Choose Next: Tags.
14. (Optional) Add metadata to the user by attaching tags as key-value pairs. For more information
about using tags in IAM, see Tagging IAM entities in the IAM User Guide.
15. Choose Next: Review to see the list of group memberships to be added to the new user. When you
are ready to proceed, choose Create user.
You can use this same process to create more groups and users and to give your users access to your AWS
account resources. To learn about using policies that restrict user permissions to specific AWS resources,
see Access management and Example policies.
Step 2: Configure permissions for IDT
In this step, configure the permissions that IDT uses to run tests and collect IDT usage data. You can use
the AWS Management Console or AWS Command Line Interface (AWS CLI) to create an IAM policy and a
user for IDT, and then attach policies to the user.
• To Configure Permissions for IDT (Console) (p. 902)
• To Configure Permissions for IDT (AWS CLI) (p. 903)
To configure permissions for IDT (console)
Follow these steps to use the console to configure permissions for IDT for AWS IoT Greengrass.
1. Sign in to the IAM console.
2. Create a customer managed policy that grants permissions to create roles with specific permissions.
a. In the navigation pane, choose Policies, and then choose Create policy.
b. On the JSON tab, replace the placeholder content with the following policy.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot-device-tester:SendMetrics"
],
"Resource": "*"
}
]
}
c. Choose Review policy.
d. For Name, enter IDTUsageMetricsIAMPermissions. Under Summary, review the
permissions granted by your policy.
e. Choose Create policy.
3. Create an IAM user and attach permissions to the user.
a. Create an IAM user. Follow steps 1 through 5 in Creating IAM users (console) in the IAM User
Guide. If you already created an IAM user, skip to the next step.
b. Attach the permissions to your IAM user:
i. On the Set permissions page, choose Attach existing policies to user directly.
ii. Search for the IDTUsageMetricsIAMPermissions policy that you created in the previous
step. Select the check box.
902
AWS IoT Greengrass Developer Guide, Version 2
IDT usage metrics
c. Choose Next: Tags.
d. Choose Next: Review to view a summary of your choices.
e. Choose Create user.
f. To view the user's access keys (access key IDs and secret access keys), choose Show next to the
password and access key. To save the access keys, choose Download.csv and save the file to a
secure location. You use this information later to configure your AWS credentials file.
To configure permissions for IDT (AWS CLI)
Follow these steps to use the AWS CLI to configure permissions for IDT for AWS IoT Greengrass.
1. On your computer, install and configure the AWS CLI if it's not already installed. Follow the steps in
Installing the AWS CLI in the AWS Command Line Interface User Guide.
Note
The AWS CLI is an open source tool that you can use to interact with AWS services from
your command-line shell.
2. Create the following customer managed policy that grants permissions to manage IDT and AWS IoT
Greengrass roles.
Linux or Unix
aws iam create-policy --policy-name IDTUsageMetricsIAMPermissions --policy-document
'{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot-device-tester:SendMetrics"
],
"Resource": "*"
}
]
}'
Windows command prompt
aws iam create-policy --policy-name IDTUsageMetricsIAMPermissions --policy-document
'{\"Version\": \"2012-10-17\", \"Statement
\": [{\"Effect\": \"Allow\", \"Action\": [\"iot-device-tester:SendMetrics\"],
\"Resource": \"*\"}]}'
Note
This step includes a Windows command prompt example because it uses a different
JSON syntax than Linux, macOS, or Unix terminal commands.
PowerShell
aws iam create-policy --policy-name IDTUsageMetricsIAMPermissions --policy-document
'{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot-device-tester:SendMetrics"
903
AWS IoT Greengrass Developer Guide, Version 2
IDT usage metrics
],
"Resource": "*"
}
]
}'
3. Create an IAM user and attach the permissions required by IDT for AWS IoT Greengrass.
a. Create an IAM user.
aws iam create-user --user-name user-name
b. Attach the IDTUsageMetricsIAMPermissions policy you created to your IAM user. Replace
user-name with your IAM user name and <account-id> in the command with the ID of your
AWS account.
aws iam attach-user-policy --user-name user-name --policy-arn
arn:aws:iam::<account-id>:policy/IDTGreengrassIAMPermissions
4. Create a secret access key for the user.
aws iam create-access-key --user-name user-name
Store the output in a secure location. You use this information later to configure your AWS
credentials file.
Provide AWS credentials to IDT
To allow IDT to access your AWS credentials and submit metrics to AWS, do the following:
1. Store the AWS credentials for your IAM user as environment variables or in a credentials file:
a. To use environment variables, run the following commands.
Linux or Unix
export AWS_ACCESS_KEY_ID=access-key
export AWS_SECRET_ACCESS_KEY=secret-access-key
Windows Command Prompt (CMD)
set AWS_ACCESS_KEY_ID=access-key
set AWS_SECRET_ACCESS_KEY=secret-access-key
PowerShell
$env:AWS_ACCESS_KEY_ID="access-key"
$env:AWS_SECRET_ACCESS_KEY="secret-access-key"
b. To use the credentials file, add the following information to the ~/.aws/credentials file.
[profile-name]
aws_access_key_id=access-key
aws_secret_access_key=secret-access-key
2. Configure the auth section of the config.json file. For more information, see (Optional)
Configure config.json (p. 892).
904
AWS IoT Greengrass Developer Guide, Version 2
Troubleshooting IDT for AWS IoT Greengrass V2
Troubleshooting IDT for AWS IoT Greengrass V2
IDT for AWS IoT Greengrass V2 writes errors to various locations based on the type of errors. IDT writes
errors to the console, log files, and test reports.
Where to look for errors
High-level errors display on the console while the test is running, and a summary of the failed tests
displays when all tests are complete. awsiotdevicetester_report.xml contains a summary of all
the errors that caused a test to fail. IDT stores the log files for each test run in a directory named with a
UUID for the test execution, displayed on the console during the test run.
The IDT test logs directory is <device-tester-extract-location>/results/<execution-id>/
logs/. This directory contains the following files, which are useful for debugging.
File Description
test_manager.log The logs written to the console while the test was
running. The summary of the results at the end of
this file includes a list of which tests failed.
The warning and error logs in this file can give you
some information about the failures.
test-group-id/test-case-id/test- Detailed logs for the specific test in a test group.
name.log For tests that deploy Greengrass components, the
test case log file is called greengrass-test-
run.log.
test-group-id/test-case-id/ Detailed logs for AWS IoT Greengrass Core
greengrass.log software. IDT copies this file from the device
under test when it runs tests that install AWS
IoT Greengrass Core software on the device. For
more information about the messages in this log
file, see Troubleshooting AWS IoT Greengrass
V2 (p. 911).
test-group-id/test-case-id/component- Detailed logs for Greengrass components that are
name.log deployed during test runs. IDT copies component
log files from the device under test when it runs
tests that deploys specific components. The
name of each component log file corresponds
to the name of the deployed component. For
more information about the messages in this log
file, see Troubleshooting AWS IoT Greengrass
V2 (p. 911).
Resolving IDT for AWS IoT Greengrass V2 errors
Before you run IDT for AWS IoT Greengrass, get the correct configuration files in place. If you receive
parsing and configuration errors, your first step is to locate and use a configuration template appropriate
for your environment.
If you are still having issues, see the following debugging process.
905
AWS IoT Greengrass Developer Guide, Version 2
Resolving IDT for AWS IoT Greengrass V2 errors
Topics
• Command not found errors while testing (p. 906)
• Conflict errors (p. 906)
• Could not start test error (p. 906)
• Docker qualification image exists errors (p. 907)
• Machine learning qualification errors (p. 907)
• Parsing errors (p. 907)
• Permission denied errors (p. 907)
• Qualification report generation error (p. 908)
• Required parameter missing error (p. 908)
• Security exception on macOS (p. 908)
• SSH connection errors (p. 908)
• Stream manager qualification errors (p. 908)
• Throttling errors during Docker qualification (p. 909)
• Timeout errors (p. 909)
• Version check errors (p. 909)
Command not found errors while testing
You need an older version of the OpenSSL library (libssl1.0.0) to run tests on AWS IoT Greengrass
devices. Most current Linux distributions use libssl version 1.0.2 or later (v1.1.0).
For example, on a Raspberry Pi, run the following commands to install the required version of libssl:
1.
wget http://ftp.us.debian.org/debian/pool/main/o/openssl/
libssl1.0.0_1.0.2l-1~bpo8+1_armhf.deb
2.
sudo dpkg -i libssl1.0.0_1.0.2l-1~bpo8+1_armhf.deb
Conflict errors
You might see the following error when you run the AWS IoT Greengrass qualification suite concurrently
on more than one device.
ConflictException: Component [com.example.IDTHelloWorld : 1.0.0] for account [account-id]
already exists with state: [DEPLOYABLE] { RespMetadata: { StatusCode: 409, RequestID:
“id” }, Message_: “Component [com.example.IDTHelloWorld : 1.0.0] for account [account-id]
already exists with state: [DEPLOYABLE]” }
Concurrent test execution isn't yet supported for the AWS IoT Greengrass qualification suite. Run the
qualification suite sequentially for each device.
Could not start test error
You might encounter errors that point to failures that occurred when the test was attempting to start.
There are several possible causes, so do the following:
• Make sure that the pool name in your execution command actually exists. IDT references the pool
name directly from your device.json file.
906
AWS IoT Greengrass Developer Guide, Version 2
Resolving IDT for AWS IoT Greengrass V2 errors
• Make sure that the devices in your pool have correct configuration parameters.
Docker qualification image exists errors
The Docker application manager qualification tests use the amazon/amazon-ec2-metadata-mock
container image in Docker Hub to qualify the device under test.
You might receive the following error if the image is already present in a Docker container on the device
under test.
The Docker image amazon/amazon-ec2-metadata-mock:version already exists on the device.
If you previously downloaded this image and ran the amazon/amazon-ec2-metadata-mock container
on your device, make sure you remove this image from the device under test before you run the
qualification tests.
Machine learning qualification errors
When you run machine learning (ML) qualification tests, you might encounter qualification failures if
your device doesn't meet the requirements (p. 319) to deploy the AWS-provided ML components. To
troubleshoot ML qualification errors, do the following:
• Look for error details in the component logs for the components that were deployed during
the test run. Component logs are located in the <device-tester-extract-location>/
results/<execution-id>/logs/<test-group-id> directory.
• Add the -Dgg.persist=installed.software argument to the test.json file for the failing
test case. The test.json file is located in the <device-tester-extract-location>/tests/
GGV2Q_version directory.
Parsing errors
Typos in a JSON configuration can lead to parsing errors. Most of the time, the issue is a result of
omitting a bracket, comma, or quotation mark from your JSON file. IDT performs JSON validation and
prints debugging information. It prints the line where the error occurred, the line number, and the
column number of the syntax error. This information should be enough to help you fix the error, but if
you still can't locate the error, you can perform validation manually in your IDE, a text editor such as
Atom or Sublime, or through an online tool like JSONLint.
Permission denied errors
IDT performs operations on various directories and files in a device under test. Some of these operations
require root access. To automate these operations, IDT must be able to run commands with sudo without
typing a password.
Follow these steps to allow sudo access without typing a password.
Note
user and username refer to the SSH user used by IDT to access the device under test.
1. Use sudo usermod -aG sudo <ssh-username> to add your SSH user to the sudo group.
2. Sign out and then sign in for changes to take effect.
3. Open /etc/sudoers file and add the following line to the end of the file: <ssh-username>
ALL=(ALL) NOPASSWD: ALL
907
AWS IoT Greengrass Developer Guide, Version 2
Resolving IDT for AWS IoT Greengrass V2 errors
Note
As a best practice, we recommend that you use sudo visudo when you edit /etc/sudoers.
Qualification report generation error
IDT supports the four latest major.minor versions of the AWS IoT Greengrass V2 qualification suite
(GGV2Q) to generate qualification reports that you can submit to AWS Partner Network to include your
devices in the AWS Partner Device Catalog. Earlier versions of the qualification suite don’t generate
qualification reports.
If you have questions about the support policy, contact AWS Support at https://aws.amazon.com/
contact-us/.
Required parameter missing error
When IDT adds new features, it might introduce changes to the configuration files. Using an old
configuration file might break your configuration. If this happens, the <test_case_id>.log file under
/results/<execution-id>/logs explicitly lists all missing parameters. IDT also validates your JSON
configuration file schemas to verify that you are using the latest supported version.
Security exception on macOS
When you run IDT on a host computer that uses macOS 10.15, the notarization ticket for IDT
isn't detected, which blocks IDT from being run. To run IDT, grant a security exception to the
devicetester_mac_x86-64 executable. Do one of the following:
To grant a security exception to IDT executables
1. Launch System Preferences from the Apple menu.
2. Choose Security & Privacy, then on the General tab, choose the lock icon to make changes to
security settings.
3. Look for the message "devicetester_mac_x86-64" was blocked from use because it
is not from an identified developer. and choose Allow Anyway.
4. Accept the security warning.
SSH connection errors
When IDT can't connect to a device under test, it logs connection failures in /results/<execution-
id>/logs/<test-case-id>.log. SSH messages appear at the top of this log file because connecting
to a device under test is one of the first operations that IDT performs.
Most Windows configurations use the PuTTy terminal application to connect to Linux hosts. This
application requires that you convert standard PEM private key files into a proprietary Windows format
called PPK. If you configure SSH in your device.json file, use PEM files. If you use a PPK file, IDT can't
create an SSH connection with the AWS IoT Greengrass device and can't run tests.
Stream manager qualification errors
When you run stream manager qualification tests, you might see the following error in the
com.aws.StreamManagerExport.log file.
Failed to upload data to S3
908
AWS IoT Greengrass Developer Guide, Version 2
Resolving IDT for AWS IoT Greengrass V2 errors
This error can occur when stream manager uses the AWS credentials in the ~/root/.aws/
credentials file on your device instead of using the environment credentials that IDT exports to the
device under test. To prevent this issue, delete the credentials file on your device, and re-run the
qualification test.
Throttling errors during Docker qualification
Docker Hub limits the number of pull requests that anonymous and Free Docker Hub users can make.
When you run IDT tests for Docker qualification, you might receive one of the following errors if you
exceed the rate limits for anonymous or free user pull requests:
ERROR: toomanyrequests: Too Many Requests.
You have reached your pull rate limit.
To resolve these errors, you can wait for a few hours before you run the qualification test. If you plan
on consistently running a large number of tests, which can result in submitting a large number of pull
requests, see the Docker Hub website for information about rate limits, and options for authenticating
and upgrading your Docker account.
Timeout errors
You can increase the timeout for each test by specifying a timeout multiplier applied to the default value
of each test's timeout. Any value configured for this flag must be greater than or equal to 1.0.
To use the timeout multiplier, use the flag --timeout-multiplier when running the tests. For
example:
./devicetester_linux run-suite --suite-id GGV2Q_1.0.0 --pool-id DevicePool1 --timeout-
multiplier 2.5
For more information, run run-suite --help.
Some timeout errors occur when IDT test cases can’t be completed because of configuration issues.
You can’t resolve these errors by increasing the timeout multiplier. Use the logs from the test run to
troubleshoot the underlying configuration issues.
• If the MQTT or Lambda component logs contain Access denied errors, your Greengrass installation
folder might not have the correct file permissions. Run the following command for each folder in the
installation path that you defined in your userdata.json file.
sudo chmod 755 folder-name
• If the Greengrass logs indicate that the Greengrass CLI deployment isn't complete, do the following:
• Verify that bash is installed on the device under test.
• If your userdata.json file includes the GreengrassCliVersion configuration parameter,
remove it. This parameter is deprecated in IDT v4.1.0 and later versions. For more information, see
Configure userdata.json (p. 840).
Version check errors
IDT issues the following error when the AWS user credentials for the IDT user don't have the required IAM
permissions.
909
AWS IoT Greengrass Developer Guide, Version 2
Support policy for AWS IoT Device
Tester for AWS IoT Greengrass
Failed to check version compatibility
The AWS user that doesn't have the required IAM permissions.
Support policy for AWS IoT Device Tester for AWS
IoT Greengrass
AWS IoT Device Tester for AWS IoT Greengrass is a test automation tool used to validate and qualify your
AWS IoT Greengrass devices for inclusion in the AWS Partner Device Catalog. We recommend that you
use the most recent version of AWS IoT Greengrass and AWS IoT Device Tester to test or qualify your
devices.
At least one version of AWS IoT Device Tester is available for each supported version of AWS IoT
Greengrass. For supported versions of AWS IoT Greengrass, see Greengrass nucleus versions (p. 181). For
supported versions of AWS IoT Device Tester, see Supported versions of AWS IoT Device Tester for AWS
IoT Greengrass V2 (p. 818).
For each version of AWS IoT Device Tester, the three latest test suite versions are supported for
qualification of devices.
You can also use any of the supported versions of AWS IoT Greengrass and AWS IoT Device Tester to
test or qualify your devices. Although you can continue to use unsupported versions of AWS IoT Device
Tester, those versions do not receive bug fixes or updates. If you have questions about the support policy,
contact AWS Support.
910
AWS IoT Greengrass Developer Guide, Version 2
View AWS IoT Greengrass Core
software and component logs
Troubleshooting AWS IoT Greengrass
V2
Use the troubleshooting information and solutions in this section to help resolve issues with AWS IoT
Greengrass Version 2.
Topics
• View AWS IoT Greengrass Core software and component logs (p. 911)
• AWS IoT Greengrass Core software issues (p. 911)
• AWS IoT Greengrass cloud issues (p. 913)
• Core device deployment issues (p. 913)
• Core device component issues (p. 917)
• AWS Command Line Interface issues (p. 918)
View AWS IoT Greengrass Core software and
component logs
The AWS IoT Greengrass Core software writes logs to the local file system that you can use to view real-
time information about the core device. You can also configure core devices to write logs to CloudWatch
Logs, so you can remotely troubleshoot core devices. These logs can help you identify issues with
components, deployments, and core devices. For more information, see Monitor AWS IoT Greengrass
logs (p. 506).
AWS IoT Greengrass Core software issues
Troubleshoot AWS IoT Greengrass Core software issues.
Topics
• Unable to set up core device (p. 911)
• Unable to set up nucleus as a system service (p. 912)
• Unable to connect to AWS IoT Core (p. 912)
• Out of memory error (p. 912)
• Unable to install Greengrass CLI (p. 912)
• User root is not allowed to execute (p. 913)
• Failed to map segment from shared object: operation not permitted (p. 913)
Unable to set up core device
If the AWS IoT Greengrass Core software installer fails and you aren't able to set up a core device, you
might need to uninstall the software and try again. For more information, see Uninstall the AWS IoT
Greengrass Core software (p. 172).
911
AWS IoT Greengrass Developer Guide, Version 2
Unable to set up nucleus as a system service
Unable to set up nucleus as a system service
You might see this error when the AWS IoT Greengrass Core software installer fails to set up AWS IoT
Greengrass as a system service. On Linux devices, this error typically occurs if the core device doesn't
have the systemd init system. The installer can successfully set up the AWS IoT Greengrass Core software
even if it fails to set up the system service.
Do one of the following:
• Configure and run the AWS IoT Greengrass Core software as a system service. You must configure the
software as a system service to use all of the features of AWS IoT Greengrass. You can install systemd
or use a different init system. For more information, see Configure the Greengrass nucleus as a system
service (p. 158).
• Run the AWS IoT Greengrass Core software without a system service. You can run the software using a
loader script that the installer sets up in the Greengrass root folder. For more information, see Run the
AWS IoT Greengrass Core software without a system service (p. 130).
Unable to connect to AWS IoT Core
You might see this error when the AWS IoT Greengrass Core software can't connect to AWS IoT Core to
retrieve deployment jobs, for example. Do the following:
• Check that your core device can connect to the internet and AWS IoT Core. For more information about
the AWS IoT Core endpoint to which your device connects, see Configure the AWS IoT Greengrass Core
software (p. 157).
• Check that your core device's AWS IoT thing uses a certificate that allows the iot:Connect,
iot:Publish, iot:Receive, and iot:Subscribe permissions.
• If your core device uses a network proxy (p. 167), check that your core device has a device role (p. 790)
and that its role allows the iot:Connect, iot:Publish, iot:Receive, and iot:Subscribe
permissions.
Out of memory error
This error typically occurs if your device doesn't have sufficient memory to allocate an object in the
Java heap. On devices with limited memory, you might need to specify a maximum heap size to control
memory allocation. For more information, see Control memory allocation with JVM options (p. 160).
Unable to install Greengrass CLI
You might see the following console message when you use the --deploy-dev-tools argument in
your installation command for AWS IoT Greengrass Core.
Thing group exists, it could have existing deployment and devices, hence NOT creating
deployment for Greengrass first party dev tools, please manually create a deployment if
you wish to
This occurs when the Greengrass CLI component is not installed because your core device is a member
of a thing group that has an existing deployment. If you see this message, you can manually deploy the
Greengrass CLI component (aws.greengrass.Cli) to the device to install the Greengrass CLI. For more
information, see Install the Greengrass CLI (p. 428).
912
AWS IoT Greengrass Developer Guide, Version 2
User root is not allowed to execute
User root is not allowed to execute
You might see this error when the user that runs the AWS IoT Greengrass Core software (typically root)
doesn't have permission to run sudo with any user and any group. For the default ggc_user system
user, this error looks like the following:
Sorry, user root is not allowed to execute <command> as ggc_user:ggc_group.
Check that your /etc/sudoers file gives the user permission to run sudo as other groups. The
permission for the user in /etc/sudoers should look like the following example.
root ALL=(ALL:ALL) ALL
Failed to map segment from shared object: operation
not permitted
This error typically occurs when the AWS IoT Greengrass Core software fails to start because the /tmp
directory is mounted with noexec permissions.
Run the following command to remount the /tmp directory with exec permissions and try again.
sudo mount -o remount,exec /tmp
AWS IoT Greengrass cloud issues
Use the following information to troubleshoot issues with the AWS IoT Greengrass console and API. Each
entry corresponds to an error message that you might see when you perform an action.
An error occurred (AccessDeniedException) when
calling the CreateComponentVersion operation: User:
arn:aws:iam::123456789012:user/<username> is not
authorized to perform: null
You might see this error when you create a component version from the AWS IoT Greengrass console or
with the CreateComponentVersion operation.
This error indicates that your recipe isn't valid JSON or YAML. Check the syntax of your recipe, fix any
syntax issues, and try again. You can use an online JSON or YAML syntax checker to identify syntax issues
in your recipe.
Core device deployment issues
Troubleshoot deployment issues on Greengrass core devices. Each entry corresponds to a log message
that you might see on your core device.
Topics
• Error: com.aws.greengrass.componentmanager.exceptions.PackageDownloadException: Failed to
download artifact (p. 914)
913
AWS IoT Greengrass Developer Guide, Version 2
Error:
com.aws.greengrass.componentmanager.exceptions.PackageDownloadException:
Failed to download artifact
• Error: com.aws.greengrass.componentmanager.exceptions.ArtifactChecksumMismatchException:
Integrity check for downloaded artifact failed. Probably due to file corruption. (p. 914)
• Error: com.aws.greengrass.componentmanager.exceptions.NoAvailableComponentVersionException:
Failed to negotiate component <name> version with cloud and no local applicable version satisfying
requirement <requirements> (p. 915)
• software.amazon.awssdk.services.secretsmanager.model.SecretsManagerException: User: <user> is
not authorized to perform: secretsmanager:GetSecretValue on resource: <arn> (p. 915)
• Info:
com.aws.greengrass.deployment.exceptions.RetryableDeploymentDocumentDownloadException:
Greengrass Cloud Service returned an error when getting full deployment configuration (p. 916)
• Info: com.aws.greengrass.deployment.DeploymentDocumentDownloader: Calling Greengrass cloud
to get full deployment configuration (p. 916)
Error:
com.aws.greengrass.componentmanager.exceptions.Package
Failed to download artifact
You might see this error when the AWS IoT Greengrass Core software fails to download a component
artifact when the core device applies a deployment. The deployment fails as a result of this error.
When you receive this error, the log also includes a stack trace that you can use to identify the specific
issue. Each of the following entries corresponds to a message that you might see in the stack trace of the
Failed to download artifact error message.
software.amazon.awssdk.services.s3.model.S3Exception: null
(Service: S3, Status Code: 403, Request ID: null, ...)
The PackageDownloadException error (p. 914) might include this stack trace in the following cases:
• The component artifact isn't available at the Amazon S3 URL that you specify in the component's
recipe. Check that you uploaded the artifact to the S3 bucket and that the artifact URL matches the
Amazon S3 URL of the artifact in the bucket.
• The core device role (p. 790) doesn't allow the AWS IoT Greengrass Core software to download the
component artifact from the Amazon S3 URL that you specify in the component's recipe. Check that
the device role allows s3:GetObject for the Amazon S3 URL where the artifact is available.
Error:
com.aws.greengrass.componentmanager.exceptions.ArtifactC
Integrity check for downloaded artifact failed.
Probably due to file corruption.
You might see this error when the AWS IoT Greengrass Core software fails to download a component
artifact when the core device applies a deployment. The deployment fails because the downloaded
artifact file's checksum doesn't match the checksum that AWS IoT Greengrass calculated when you
created the component.
Do the following:
914
AWS IoT Greengrass Developer Guide, Version 2
Error:
com.aws.greengrass.componentmanager.exceptions.NoAvailableComponentVersionException:
Failed to negotiate component <name>
• Check if the artifact file changed
version within the S3 and
cloud bucket whereapplicable
no local you host it. If the file changed since you
created the component, version satisfying
restore it to therequirement <requirements>
previous version that the core device expects. If you can't
restore the file to its previous version, or if you want to use the new version of the file, create a new
version of the component with the artifact file.
• Check your core device's internet connection. This error can occur if the artifact file becomes corrupted
while it downloads. Create a new deployment and try again.
Error:
com.aws.greengrass.componentmanager.exceptions.NoAvaila
Failed to negotiate component <name> version
with cloud and no local applicable version satisfying
requirement <requirements>
You might see this error when a core device can't find a component version that meets the requirements
of the deployments for that core device. The core device checks for the component in the AWS IoT
Greengrass service and on the local device. The error message includes each deployment's target and
that deployment's version requirements for the component. The deployment target can be a thing, a
thing group, or LOCAL_DEPLOYMENT, which represents the local deployment on the core device.
This issue can occur in the following cases:
• The core device is the target of multiple deployments that have conflicting component version
requirements. For example, the core device might be the target of multiple deployments that include
a com.example.HelloWorld component, where one deployment requires version 1.0.0 and the
other requires version 1.0.1. It's impossible to have a component that meets both requirements, so the
deployment fails.
• The component version doesn't exist in the AWS IoT Greengrass service or on the local device. The
component might have been deleted, for example.
• There exists component versions that meet the version requirements, but none are compatible with
the core device's platform.
• The core device's AWS IoT policy doesn't grant the greengrass:ResolveComponentCandidates
permission. Look for Status Code: 403 in the error log to identify this issue. To resolve this
issue, add the greengrass:ResolveComponentCandidates permission to the core device's
AWS IoT policy. For more information, see Minimal AWS IoT policy for AWS IoT Greengrass V2 core
devices (p. 777).
To resolve this issue, revise the deployments to include compatible component versions or remove
incompatible ones. For more information about how to revise cloud deployments, see Revise
deployments (p. 502). For more information about how to revise local deployments, see the AWS IoT
Greengrass CLI deployment create (p. 434) command.
software.amazon.awssdk.services.secretsmanager.model.Sec
User: <user> is not authorized to perform:
secretsmanager:GetSecretValue on resource: <arn>
This error can occur when you use the secret manager component (p. 374) to deploy an AWS Secrets
Manager secret. If the core device's token exchange IAM role (p. 790) doesn't grant permission to get the
secret, the deployment fails and the Greengrass logs include this error.
915
AWS IoT Greengrass Developer Guide, Version 2
Info:
com.aws.greengrass.deployment.exceptions.RetryableDeploymentDocumentDownloadException:
Greengrass Cloud Service returned an error
To authorize a core device
whentogetting
download a secret configuration
full deployment
1. Add the secretsmanager:GetSecretValue permission to the core device's token exchange role.
The following example policy statement grants permission to get the value of a secret.
{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:us-west-2:123456789012:secret:MyGreengrassSecret-
abcdef"
]
}
For more information, see Authorize core devices to interact with AWS services (p. 790).
2. Reapply the deployment to the core device. Do one of the following:
• Revise the deployment without any changes. The core device tries to download the
secret again when it receives the revised deployment. For more information, see Revise
deployments (p. 502).
• Restart the AWS IoT Greengrass Core software to retry the deployment. For more information,
see Run the AWS IoT Greengrass Core software (p. 128)
The deployment succeeds if secret manager downloads the secret successfully.
Info:
com.aws.greengrass.deployment.exceptions.RetryableDeploy
Greengrass Cloud Service returned an error when
getting full deployment configuration
You might see this error when the core device receives a large deployment document, which is a
deployment document larger than 7 KB (for deployments that target things) or 31 KB (for deployments
that target thing groups). To retrieve a large deployment document, a core device's AWS IoT policy must
allow the greengrass:GetDeploymentConfiguration permission. This error can occur when the
core device doesn't have this permission. When this error occurs, the deployment retries indefinitely, and
its status is In progress (IN_PROGRESS).
To resolve this issue, add the greengrass:GetDeploymentConfiguration permission to the core
device's AWS IoT policy. For more information, see Update a core device's AWS IoT policy (p. 776).
Info:
com.aws.greengrass.deployment.DeploymentDocumentDown
Calling Greengrass cloud to get full deployment
configuration
You might see this information message printed multiple times without an error, because the core
device logs the error at the DEBUG log level. This issue can occur when the core device receives a large
deployment document. When this issue occurs, the deployment retries indefinitely, and its status is In
916
AWS IoT Greengrass Developer Guide, Version 2
Core device component issues
progress (IN_PROGRESS). For more information about how to resolve this issue, see this troubleshooting
entry (p. 916).
Core device component issues
Troubleshoot Greengrass component issues on core devices.
Topics
• Warn: '<command>' is not recognized as an internal or external command (p. 917)
• Python script doesn't log messages (p. 917)
Warn: '<command>' is not recognized as an internal
or external command
You might see this error in a Greengrass component's logs when the AWS IoT Greengrass Core software
fails to run a command in the component's lifecycle script. The component's state becomes BROKEN as a
result of this error. This error can occur if the system user that runs the component, such as ggc_user,
can't find the command's executable in the folders in the PATH.
On Windows devices, check that the folder that contains the executable is in the PATH for the system
user that runs the component. If it's missing from the PATH, do one of the following:
• Add the executable's folder to the PATH system variable, which is available to all users. Then, restart
the component.
If you run Greengrass nucleus 2.5.0, after you update the PATH system variable, you must restart
the AWS IoT Greengrass Core software to run components with the updated PATH. If the AWS IoT
Greengrass Core software doesn't use the updated PATH after you restart the software, restart the
device and try again. For more information, see Run the AWS IoT Greengrass Core software (p. 128).
• Add the executable's folder to the PATH user variable for the system user that runs the component.
Python script doesn't log messages
Greengrass core devices collect logs that you can use to identify issues with components. If your Python
script's stdout and stderr messages don't appear in your component logs, you might need to flush the
buffer or disable buffering for these standard output streams in Python. Do any of the following:
• Run Python with the -u argument to disable buffering on stdout and stderr.
Linux or Unix
python3 -u hello_world.py
Windows
py -3 -u hello_world.py
• Use Setenv (p. 476) in your component's recipe to set the PYTHONUNBUFFERED environment variable
to a non-empty string. This environment variable disables buffering on stdout and stderr.
• Flush the buffer for the stdout or stderr streams. Do one of the following:
• Flush a message when you print.
917
AWS IoT Greengrass Developer Guide, Version 2
AWS CLI issues
import sys
print('Hello, error!', file=sys.stderr, flush=True)
• Flush a message after you print. You can send multiple messages before you flush the stream.
import sys
print('Hello, error!', file=sys.stderr)
sys.stderr.flush()
For more information about how to verify that your Python script outputs log messages, see Monitor
AWS IoT Greengrass logs (p. 506).
AWS Command Line Interface issues
Troubleshoot AWS CLI issues for AWS IoT Greengrass V2.
Topics
• Error: Invalid choice: 'greengrassv2' (p. 918)
Error: Invalid choice: 'greengrassv2'
You might see this error when you run an AWS IoT Greengrass V2 command with the AWS CLI (for
example, aws greengrassv2 list-core-devices).
This error indicates that you have a version of the AWS CLI that doesn't support AWS IoT Greengrass V2.
To use AWS IoT Greengrass V2 with the AWS CLI, you must have one of the following versions or later:
• Minimum AWS CLI V1 version: v1.18.197
• Minimum AWS CLI V2 version: v2.1.11
Tip
You can run the following command to check the version of the AWS CLI that you have.
aws --version
To resolve this issue, update the AWS CLI to a later version that supports AWS IoT Greengrass V2. For
more information, see Installing, updating, and uninstalling the AWS CLI in the AWS Command Line
Interface User Guide.
918
AWS IoT Greengrass Developer Guide, Version 2
Using tags in AWS IoT Greengrass V2
Tag your AWS IoT Greengrass
Version 2 resources
With tags, you can organize and manage your resources in AWS IoT Greengrass. You can use tags to
assign metadata to your resources, and you can use tags in IAM policies to define conditional access to
your resources.
Using tags in AWS IoT Greengrass V2
You can use tags to categorize your AWS IoT Greengrass resources by purpose, owner, environment, or
any other classification for your use case. When you have many resources of the same type, tags help you
more readily identify a specific resource.
Each tag consists of a key and an optional value, both of which you define. For example, you could define
a set of tags for your core devices that helps you track them by the customers who own the devices. We
recommend that you create a set of tag keys that meets your needs for each kind of resource. By using a
consistent set of tag keys, you can more easily manage your resources.
Tag with the AWS Management Console
The Tag Editor in the AWS Management Console provides a central, unified way for you to create and
manage your tags for resources from all AWS services. For more information, see Tag Editor in the AWS
Resource Groups User Guide.
Tag with the AWS IoT Greengrass V2 API
You can also use the AWS IoT Greengrass V2 API to work with tags. Before you create tags, be aware of
tagging restrictions. For more information, see Tag naming and usage conventions in the AWS General
Reference.
• To add tags when you create a resource, define them in the tags property of the resource.
• To add tags to an existing resource, or to update tag values, use the TagResource operation.
• To remove tags from a resource, use the UntagResource operation.
• To retrieve the tags that are associated with a resource, use the ListTagsForResource operation, or
describe the resource and inspect its tags property.
The following table lists resources that you can tag using the AWS IoT Greengrass V2 API and their
corresponding Create and Describe or Get operations.
Taggable AWS IoT Greengrass V2 resources
Resource Create operation Describe or get operation
Core device None. Run the AWS IoT GetCoreDevice
Greengrass Core software on a
device to create a core device.
919
AWS IoT Greengrass Developer Guide, Version 2
Using tags with IAM policies
Resource Create operation Describe or get operation
Component CreateComponentVersion DescribeComponent,
GetComponent
Deployment CreateDeployment GetDeployment
Use the following operations to view and manage tags for resources that support tagging:
• TagResource – Adds tags to a resource, or updates an existing tag's value.
• ListTagsForResource – Lists the tags for a resource.
• UntagResource – Removes tags from a resource.
You can add or remove tags for a resource at any time. To change the value of a tag key, add a tag to the
resource that defines the same key and the new value. The new value replaces the previous value. You
can set a value to an empty string, but you can't set a value to null.
When you delete a resource, tags that are associated with that resource are also deleted.
Using tags with IAM policies
In your IAM policies, you can use resource tags to control user access and permissions. For example,
policies can allow users to create only those resources that have a specific tag. Policies can also restrict
users from creating or modifying resources that have certain tags.
Note
If you use tags to allow or deny users' access to resources, you should deny users the ability
to add or remove those tags for the same resources. Otherwise, a user could circumvent your
restrictions and gain access to a resource by modifying its tags.
You can use the following condition context keys and values in the Condition element, also called the
Condition block, of a policy statement.
greengrassv2:ResourceTag/tag-key: tag-value
Allow or deny actions on resources with specific tags.
aws:RequestTag/tag-key: tag-value
Require that a specific tag be used, or not used, when creating or modifying a taggable resource.
aws:TagKeys: [tag-key, ...]
Require that a specific set of tag keys be used, or not used, when creating or modifying a taggable
resource.
Note
The condition context keys and values in an IAM policy apply only to actions that have a
taggable resource as a required parameter. For example, you can set tag-based conditional
access for ListCoreDevices.
For more information, see Controlling access to AWS resources using resource tags and IAM JSON policy
reference in the IAM User Guide.
920
AWS IoT Greengrass Developer Guide, Version 2
Open source AWS IoT Greengrass
Core software
The AWS IoT Greengrass Version 2 edge runtime (nucleus) and other components of the AWS IoT
Greengrass Core software are open source. This means that you can review the code to troubleshoot
interactions with your applications. You can also customize and extend the AWS IoT Greengrass Core
software to meet your specific software and hardware needs.
For information about the open source repositories for the AWS IoT Greengrass Core software, see the
aws-greengrass organization on GitHub. Your use of open source software is governed by the open
source license in the corresponding GitHub repository.
Your use of the AWS IoT Greengrass Core software and components not subject to an open source
license is governed by the AWS Greengrass Core Software License.
921
AWS IoT Greengrass Developer Guide, Version 2
Document history for the AWS IoT
Greengrass V2 Developer Guide
The following table describes the documentation for this release of AWS IoT Greengrass Version 2.
• API version: 2020-11-30
update-history-change update-history-description update-history-date
AWS IoT Device Tester v4.4.1 Version 4.4.1 of IDT for AWS IoT December 6, 2021
with GGV2Q v2.2.0 released Greengrass V2 is available. This
release includes the AWS IoT
Greengrass V2 qualification suite
(GGV2Q) v2.2.0, and supports
Greengrass nucleus version 2.5.2
for device qualification.
AWS IoT Greengrass Core v2.5.2 This release provides version December 3, 2021
software update 2.5.2 of the Greengrass nucleus
component and updates AWS-
provided components. It fixes
an issue with the Windows
service that occurs after the
Greengrass nucleus updates.
It also includes support for
the AWS IoT Device Defender
component on Windows devices.
New edge connector for Kinesis Version 1.0.0 of the edge November 30, 2021
Video Streams component connector for Kinesis Video
Streams component is available.
This AWS-provided reads video
feeds from local cameras
and publishes the streams to
Kinesis Video Streams. This
component integrates with
AWS IoT TwinMaker, which
enables you to view and manage
video streams and other data in
Grafana dashboards.
Manage Greengrass core devices Added information about how to November 29, 2021
with AWS Systems Manager manage Greengrass core devices
with AWS Systems Manager.
Systems Manager is an AWS
service that enables you to view
operational data, automate
operation tasks, and maintain
security and compliance.
Greengrass Development Kit CLI Added information about November 29, 2021
the AWS IoT Greengrass
922
AWS IoT Greengrass Developer Guide, Version 2
Development Kit Command-
Line Interface (GDK CLI), which
is a tool that you can download
to your local development
computer to help you develop
custom Greengrass components.
You can use the GDK CLI to
create, build, and publish custom
components.
Community-provided Added information about the November 29, 2021
Greengrass components Greengrass Software Catalog,
which is an index of Greengrass
components that are developed
by the Greengrass community.
From this catalog, you can
download, modify, and deploy
components to create your
Greengrass applications.
AWS IoT Greengrass Core v2.5.1 This release provides version November 23, 2021
software update 2.5.1 of the Greengrass nucleus
component and updates AWS-
provided components. It
includes support for 32-bit Java
on Windows devices. It also fixes
issues with the new thing group
removal behavior and loading
system environment variables on
Windows devices.
AWS IoT Device Tester v4.4.0 Version 4.4.0 of IDT for AWS IoT November 19, 2021
with GGV2Q v2.1.0 released Greengrass V2 is available. This
release includes the AWS IoT
Greengrass V2 qualification suite
(GGV2Q) v2.1.0, and supports
qualification of Windows-based
Greengrass devices running
Greengrass nucleus version
2.5.0.
AWS IoT Greengrass Core v2.5.0 This release provides version November 12, 2021
software update 2.5.0 of the Greengrass nucleus
component and updates AWS-
provided components. It
includes support for running
the AWS IoT Greengrass Core
software on Windows devices.
It also changes the thing group
removal behavior and adds
support for HTTPS proxies.
923
AWS IoT Greengrass Developer Guide, Version 2
SageMaker Edge Manager v1.1.0 Amazon SageMaker Edge November 3, 2021
released Manager component v1.1.0
is available. This release adds
support for Greengrass core
devices running Amazon Linux
2, and adds a new configuration
parameter to specify the
location of the capture data
folder on your device.
Cross-service confused deputy AWS IoT Greengrass V2 supports November 1, 2021
prevention update using the aws:SourceArn and
aws:SourceAccount global
condition context keys in IAM
resource policies to prevent the
confused deputy problem.
Client device component Client device auth v2.0.3, IP October 28, 2021
updates detector v2.1.0, MQTT bridge
v2.1.0, and MQTT broker
(Moquette) v2.0.2 are available.
This release adds full support for
non-default MQTT broker ports
and includes other bug fixes and
improvements.
Shadow manager v2.0.4 released Lambda manager component October 20, 2021
v2.0.4 is available. This
release fixes an issue that
caused shadow manager
to delete newly created
versions of any shadow that
was previously deleted.
Beginning with this release,
the DeleteThingShadow
IPC operation increments the
shadow version.
Log manager v2.2.0 released Log manager component v2.2.0 October 20, 2021
is available. Log manager now
supports using a configuration
map to provide component log
configurations.
Lambda manager v2.1.4 Lambda manager component October 20, 2021
released v2.1.4 is available. This release
fixes an issue that caused
Lambda functions that use
NodeJS runtimes to process only
one message.
Use interprocess communication, Added information about how to October 19, 2021
AWS credentials, and stream use interprocess communication
manager in Docker container (IPC), AWS credentials, and
components stream manager in your custom
Docker container components.
924
AWS IoT Greengrass Developer Guide, Version 2
New nucleus telemetry emitter Version 1.0.0 of the nucleus September 30, 2021
component telemetry emitter component
is available. This AWS-provided
plugin component gathers
system health telemetry data
and publishes it continually to a
local topic and an AWS IoT Core
MQTT topic.
Allow device traffic through a Added information about September 16, 2021
proxy or firewall the endpoints and ports that
Greengrass core device use,
so you can restrict traffic as a
security measure.
AWS IoT Device Tester v4.2.0 Version 4.2.0 of IDT for AWS IoT August 31, 2021
with GGV2Q v2.0.1 released Greengrass V2 has been updated
with AWS IoT Greengrass V2
qualification suite (GGV2Q)
v2.0.1. This release supports
Greengrass nucleus version 2.4.0
for device qualification.
Updated machine learning DLR installer component v1.6.5 August 30, 2021
installer components and TensorFlow Lite installer
component v2.5.4 are available.
These component versions
include the new UseInstaller
configuration parameter that
lets you disable the default
installation script.
Embedded Linux support for The BitBake recipe for AWS IoT August 20, 2021
AWS IoT Greengrass Greengrass V2 is available in the
meta-aws project on GitHub.
You can use this recipe to build
a custom Linux-based operating
system using the Yocto Project.
Code integrity Added information about August 19, 2021
how AWS IoT Greengrass V2
verifies the integrity of software
that Greengrass core devices
download from the AWS Cloud.
VPC endpoints (AWS PrivateLink) AWS IoT Greengrass now August 16, 2021
supports interface VPC
endpoints (AWS PrivateLink)
for the AWS IoT Greengrass
control plane. You can establish
a private connection between
your VPC and the AWS IoT
Greengrass control plane.
925
AWS IoT Greengrass Developer Guide, Version 2
Stream manager v2.0.12 Stream manager v2.0.12 is now August 10, 2021
released available. This releases fixes an
issue that prevented upgrades
from version 2.0.7 of the stream
manager component to a version
between v2.0.8 and v2.0.11.
Dockerfile and Docker images The Dockerfile and Docker image August 9, 2021
for AWS IoT Greengrass Core for AWS IoT Greengrass v2.4.0
software v2.4.0 are now available.
AWS IoT Greengrass Core v2.4.0 This release provides version August 3, 2021
software update 2.4.0 of the Greengrass nucleus
component and updates AWS-
provided components. It
includes support for component
system resource limits, IPC
operations to pause and resume
components, and provisioning
plugins.
New AWS IoT SiteWise Added the following AWS- July 29, 2021
components provided components for AWS
IoT SiteWise: IoT SiteWise
OPC-UA collector, IoT SiteWise
publisher, and IoT SiteWise
processor.
AWS IoT Device Tester v4.2.0 Version 4.2.0 of IDT for AWS July 14, 2021
with GGV2Q v2.0.0 released IoT Greengrass V2 is available.
This release includes the AWS
IoT Greengrass V2 qualification
suite (GGV2Q) v2.0.0 and
includes support for optional
qualification tests for Docker
components, machine learning,
and stream manager.
AWS IoT Greengrass Core IPC Version 1.13.0 of the AWS IoT July 14, 2021
library available in AWS IoT Device SDK for C++ v2 supports
Device SDK for C++ v2 AWS IoT Greengrass Core IPC, so
you can develop components in
C++ that interact with the AWS
IoT Greengrass Core software.
SageMaker Edge Manager Amazon SageMaker Edge July 12, 2021
component v1.0.2 released Manager component v1.0.2 is
available. This release updates
the installation script in the
component lifecycle. Your core
devices must now have Python
3.6 or later, including pip for
your version of Python, installed
on the device before you deploy
this component.
926
AWS IoT Greengrass Developer Guide, Version 2
Support update for AWS IoT IDT for AWS IoT Greengrass V2 July 8, 2021
Device Tester for AWS IoT version 4.1.0 now supports using
Greengrass V2 Greengrass nucleus version 2.3.0
for device qualification.
Dockerfile and Docker images The Dockerfile and Docker image July 7, 2021
for AWS IoT Greengrass Core for AWS IoT Greengrass v2.3.0
software v2.3.0 are now available.
AWS managed policies Added information about AWS July 2, 2021
managed policies for AWS IoT
Greengrass.
New recommended JVM options Added information about June 30, 2021
recommended JVM options
to control memory allocation
for AWS IoT Greengrass Core
software.
AWS IoT Greengrass Core v2.3.0 This release provides version June 29, 2021
software update 2.3.0 of the Greengrass nucleus
component and updates
AWS-provided components.
It includes support for large
component configuration
documents in deployments.
Dockerfile and Docker images The Dockerfile and Docker image June 28, 2021
for AWS IoT Greengrass Core for AWS IoT Greengrass v2.2.0
software v2.2.0 are now available.
AWS IoT Device Tester v4.1.0 Version 4.1.0 of IDT for AWS IoT June 18, 2021
with GGV2Q v1.1.1 released Greengrass V2 is available. This
release includes the AWS IoT
Greengrass V2 qualification suite
(GGV2Q) v1.1.1 and supports
using Greengrass nucleus v2.2.0,
v2.1.0, and v2.0.5 for device
qualification.
AWS IoT Greengrass Core v2.2.0 This release provides version June 18, 2021
software update 2.2.0 of the Greengrass nucleus
component and updates AWS-
provided components. It
includes components that you
can deploy to add support for
client devices and add the local
shadow service.
Lambda launcher v2.0.6 released Version 2.0.6 of the Lambda June 13, 2021
launcher component is
available. This version includes
performance improvements and
bug fixes.
927
AWS IoT Greengrass Developer Guide, Version 2
New SageMaker Edge Manager Version 1.0.0 of the Amazon June 10, 2021
component released SageMaker Edge Manager
component is available for AWS
IoT Greengrass. This component
installs the SageMaker Edge
Manager agent binary on
Greengrass core devices.
Component types Added information about June 3, 2021
component types in AWS IoT
Greengrass. The component
type specifies how the AWS IoT
Greengrass Core software runs a
component.
AWS IoT Device Tester v4.0.2 Version 4.0.2 of IDT for AWS IoT May 5, 2021
with GGV2Q v1.1.0 released Greengrass V2 is available. This
release includes the AWS IoT
Greengrass V2 qualification suite
(GGV2Q) v1.1.0 and supports
using Greengrass nucleus v2.1.0
with Greengrass CLI v2.1.0
for device qualification. This
also includes new required test
groups for MQTT and Lambda,
and other minor bug fixes and
improvements.
Dockerfile and Docker images The Dockerfile and Docker image April 27, 2021
for AWS IoT Greengrass Core for AWS IoT Greengrass v2.1.0
software v2.1.0 are now available. The Docker
image enables you to run AWS
IoT Greengrass in a Docker
container that uses Amazon
Linux 2 as the base operating
system.
AWS IoT Greengrass Core v2.1.0 This release provides version April 26, 2021
software update 2.1.0 of the Greengrass nucleus
component and updates AWS-
provided components. It
includes a new component that
you can use to download Docker
images from private Amazon
ECR repositories, and new
sample components to perform
machine learning inference using
TensorFlow Lite.
Example component that uses Added an example component April 8, 2021
Secrets Manager that prints the value of an AWS
Secrets Manager secret that you
deploy to a core device.
928
AWS IoT Greengrass Developer Guide, Version 2
Minimal AWS IoT policy for Added information about the April 2, 2021
Greengrass core devices minimal set of permissions
required to support basic
Greengrass functionality on a
core device.
Subscribe to IPC event streams Added information about how to April 1, 2021
use interprocess communication
(IPC) operations to subscribe
to streams of events on a
Greengrass core device.
Support update for AWS IoT IDT for AWS IoT Greengrass V2 March 17, 2021
Device Tester for AWS IoT version 4.0.1 now supports using
Greengrass Greengrass nucleus version 2.0.5
with Greengrass CLI version
2.0.5 for device qualification.
Create custom components that Added information about March 9, 2021
use stream manager how to configure component
recipes and artifacts to develop
applications that manage data
streams.
AWS IoT Greengrass Core v2.0.5 This release provides version March 9, 2021
software update 2.0.5 of the Greengrass nucleus
component and updates AWS-
provided components. It fixes
an issue with network proxy
support and an issue with the
Greengrass data plane endpoint
in AWS China Regions.
Component environment Added information about the February 23, 2021
variable reference environment variables that
the AWS IoT Greengrass Core
software sets for components.
You can use these environment
variables to get the thing name,
AWS Region, and Greengrass
nucleus version.
Manual installation Added information about how to February 17, 2021
create required AWS resources
manually or to install behind
a firewall or network proxy. By
using a manual installation, you
don't need to give the installer
permission to create resources
in your AWS account, because
you create the the required AWS
IoT and IAM resources. You can
also configure your device to
connect on port 443 or through
a network proxy.
929
AWS IoT Greengrass Developer Guide, Version 2
AWS IoT Greengrass Core IPC Version 1.5.4 of the AWS IoT February 11, 2021
library update in AWS IoT Device Device SDK for Python v2
SDK for Python v2 simplifies the steps required
to connect to the AWS IoT
Greengrass Core IPC service.
Support update for AWS IoT IDT for AWS IoT Greengrass V2 February 5, 2021
Device Tester for AWS IoT version 4.0.1 now supports using
Greengrass Greengrass nucleus version 2.0.4
with Greengrass CLI version
2.0.4 for device qualification.
New tutorial to import Lambda Added a new console-based February 5, 2021
functions tutorial to import a Lambda
function as a component that
runs on Greengrass core device.
AWS IoT Greengrass Core v2.0.4 This release provides version February 4, 2021
software update 2.0.4 of the Greengrass nucleus
component. It includes the new
greengrassDataPlanePort
parameter to configure HTTPS
communication over port 443
and fixes bugs. The minimal
IAM policy now requires
the iam:GetPolicy and
sts:GetCallerIdentity
when the AWS IoT Greengrass
Core software installer is run
with --provision true.
New secure tunneling Version 1.0.0 of the secure January 21, 2021
component released tunneling component
is available for AWS IoT
Greengrass. This AWS-provided
component uses AWS IoT secure
tunneling to establish secure
bidirectional communication
with a Greengrass core device
that is behind restricted
firewalls.
AWS IoT Device Tester for AWS Version 4.0.1 of IDT for AWS IoT December 22, 2020
IoT Greengrass v4.0.1 released Greengrass V2 is available. This
version enables you to use IDT
to develop and run your custom
test suites for device validation.
This also includes code signed
IDT applications for macOS and
Windows.
930
AWS IoT Greengrass Developer Guide, Version 2
Initial release of AWS IoT AWS IoT Greengrass V2 is a new December 15, 2020
Greengrass Version 2 major version release of AWS
IoT Greengrass. This version
adds several features such as
modular software components
and continuous deployments.
These features make it easier
for you to develop and manage
edge applications.
931
AWS IoT Greengrass Developer Guide, Version 2
AWS glossary
For the latest AWS terminology, see the AWS glossary in the AWS General Reference.
932
You might also like
- Iot2050 Aws Iot Greengras Getting Started EnUS en-USNo ratings yetIot2050 Aws Iot Greengras Getting Started EnUS en-US4 pages
- AWS Greengrass: Secure Local IoT ComputingNo ratings yetAWS Greengrass: Secure Local IoT Computing4 pages
- Understanding Amazon's Internet of Things (AWS IoT) Services - ENGNo ratings yetUnderstanding Amazon's Internet of Things (AWS IoT) Services - ENG7 pages
- 8.17 AWS Services Overview - Internet of ThingsNo ratings yet8.17 AWS Services Overview - Internet of Things5 pages
- 6 GEN Iot Connected Home Ebook Iot With Aws May 2018No ratings yet6 GEN Iot Connected Home Ebook Iot With Aws May 20186 pages
- Sustainability and Green Tech Edition - Draft 2No ratings yetSustainability and Green Tech Edition - Draft 24 pages
- How Amazon Is Using The Internet of Things? - Smart Speakers, Aws Iot and MoreNo ratings yetHow Amazon Is Using The Internet of Things? - Smart Speakers, Aws Iot and More6 pages
- Neoway AWS IoT Core Application Notes V1.3.20201216155848No ratings yetNeoway AWS IoT Core Application Notes V1.3.2020121615584825 pages
- Understanding The Various Applications of AWS IoT ServicesNo ratings yetUnderstanding The Various Applications of AWS IoT Services6 pages
- Review Paper-Dynamic Assurance Case-1302210024No ratings yetReview Paper-Dynamic Assurance Case-13022100242 pages
- Aws Industrial Asset Condition Monitoring RaNo ratings yetAws Industrial Asset Condition Monitoring Ra1 page
- 00-PRM02-AWS and DevOps - (Solutions Architect DevOps Engineering) - Course Content-V14.0No ratings yet00-PRM02-AWS and DevOps - (Solutions Architect DevOps Engineering) - Course Content-V14.05 pages
- AWS IoT Analytics - AWS IoT Analytics User GuideNo ratings yetAWS IoT Analytics - AWS IoT Analytics User Guide181 pages
- Using Computer Vision For Product Quality Analysis in Plants RaNo ratings yetUsing Computer Vision For Product Quality Analysis in Plants Ra1 page
- Enterprise Architecture: Dexter C. HullezaNo ratings yetEnterprise Architecture: Dexter C. Hulleza28 pages
- Test Bank For Modern Business Statistics With Microsoft Excel, 6th Edition, David R. Anderson, Dennis J. Sweeney, Thomas A. Williams, Jeffrey D. Camm James J. Cochran PDF Download100% (5)Test Bank For Modern Business Statistics With Microsoft Excel, 6th Edition, David R. Anderson, Dennis J. Sweeney, Thomas A. Williams, Jeffrey D. Camm James J. Cochran PDF Download60 pages
- Wan Introduction: © 2006 Cisco Systems, Inc. All Rights Reserved. Cisco Public ITE I Chapter 6No ratings yetWan Introduction: © 2006 Cisco Systems, Inc. All Rights Reserved. Cisco Public ITE I Chapter 637 pages
- Supply and Installation of Surface Pump, Submersible Pump and Generator 1.1 Electric Driven Surface PumpsNo ratings yetSupply and Installation of Surface Pump, Submersible Pump and Generator 1.1 Electric Driven Surface Pumps31 pages
- Digital Disruption and Transformation Case Studies Approaches and Tools Daniel Schallmo PDF Download100% (1)Digital Disruption and Transformation Case Studies Approaches and Tools Daniel Schallmo PDF Download80 pages
- Backlog Exam - Routine - Even - 2023 - 24 - Sem - 2 - 4 - 6 - 8 - Spl. SuppleNo ratings yetBacklog Exam - Routine - Even - 2023 - 24 - Sem - 2 - 4 - 6 - 8 - Spl. Supple14 pages
- RIMS ISACA Bridging The Digital Risk Gap - Res - Eng - 0919No ratings yetRIMS ISACA Bridging The Digital Risk Gap - Res - Eng - 091918 pages
- Heart Cancer Prediction Using Machine LearningNo ratings yetHeart Cancer Prediction Using Machine Learning33 pages
- Elon Musk v. Samuel Altman Et Al (Via CNBC - Com)100% (3)Elon Musk v. Samuel Altman Et Al (Via CNBC - Com)46 pages
- Harris HD-0165 Keyboard Encoder Specifications (1977)No ratings yetHarris HD-0165 Keyboard Encoder Specifications (1977)3 pages
- SIM7500 - SIM7600 Series - AT Command Manual - V1.10No ratings yetSIM7500 - SIM7600 Series - AT Command Manual - V1.10335 pages
- A Short Overview of The Technical ArchitectureNo ratings yetA Short Overview of The Technical Architecture4 pages
- Assignment-2 B.Tech-CSE-ALL Subject: Microprocessor and Embedded System Date of Submission: 30 April 2020100% (1)Assignment-2 B.Tech-CSE-ALL Subject: Microprocessor and Embedded System Date of Submission: 30 April 20203 pages
- Unsupervised Video Summarization Framework Using Keyframe Extraction and Video SkimmingNo ratings yetUnsupervised Video Summarization Framework Using Keyframe Extraction and Video Skimming6 pages
