Amazon CloudFormation support for Amazon IoT Greengrass - Amazon IoT Greengrass
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Amazon IoT Greengrass Version 1 no longer receives feature updates, and will receive only security patches and bug fixes until June 30, 2023. For more information, see the Amazon IoT Greengrass V1 maintenance policy. We strongly recommend that you migrate to Amazon IoT Greengrass Version 2, which adds significant new features and support for additional platforms.

Amazon CloudFormation support for Amazon IoT Greengrass

Amazon CloudFormation is a service that can help you create, manage, and replicate your Amazon resources. You can use Amazon CloudFormation templates to define Amazon IoT Greengrass groups and the client devices, subscriptions, and other components that you want to deploy. For an example, see Example template.

The resources and infrastructure that you generate from a template is called a stack. You can define all of your resources in one template or refer to resources from other stacks. For more information about Amazon CloudFormation templates and features, see What is Amazon CloudFormation? in the Amazon CloudFormation User Guide.

Creating resources

Amazon CloudFormation templates are JSON or YAML documents that describe the properties and relationships of Amazon resources. The following Amazon IoT Greengrass resources are supported:

  • Groups

  • Cores

  • Client devices (devices)

  • Lambda functions

  • Connectors

  • Resources (local, machine learning, and secret)

  • Subscriptions

  • Loggers (logging configurations)

In Amazon CloudFormation templates, the structure and syntax of Greengrass resources are based on the Amazon IoT Greengrass API. For example, the example template associates a top-level DeviceDefinition with a DeviceDefinitionVersion that contains an individual client device. For more information, see Overview of the Amazon IoT Greengrass group object model.

The Amazon IoT Greengrass resource types reference in the Amazon CloudFormation User Guide describes the Greengrass resources that you can manage with Amazon CloudFormation. When you use Amazon CloudFormation templates to create Greengrass resources, we recommend that you manage them only from Amazon CloudFormation. For example, you should update your template if you want to add, change, or remove a device (instead of using the Amazon IoT Greengrass API or Amazon IoT console). This allows you to use rollback and other Amazon CloudFormation change management features. For more information about using Amazon CloudFormation to create and manage your resources and stacks, see Working with stacks in the Amazon CloudFormation User Guide.

For a walkthrough that shows how to create and deploy Amazon IoT Greengrass resources in an Amazon CloudFormation template, see Automating Amazon IoT Greengrass setup with Amazon CloudFormation on The Internet of Things on Amazon Official Blog.

Deploying resources

After you create an Amazon CloudFormation stack that contains your group version, you can use the Amazon CLI or Amazon IoT console to deploy it.

Note

To deploy a group, you must have a Greengrass service role associated with your Amazon Web Services account. The service role allows Amazon IoT Greengrass to access your resources in Amazon Lambda and other Amazon services. This role should exist if you already deployed a Greengrass group in the current Amazon Web Services Region. For more information, see Greengrass service role.

To deploy the group (Amazon CLI)
  • Run the create-deployment command.

    aws greengrass create-deployment --group-id GroupId --group-version-id GroupVersionId --deployment-type NewDeployment
    Note

    The CommandToDeployGroup statement in the example template shows how to output the command with your group and group version IDs when you create a stack.

To deploy the group (console)
  1. In the Amazon IoT console navigation pane, under Manage, expand Greengrass devices, and then choose Groups (V1).

  2. Choose your group.

  3. On the group configuration page, choose Deploy.

Example template

The following example template creates a Greengrass group that contains a core, client device, function, logger, subscription, and two resources. To do this, the template follows the object model of the Amazon IoT Greengrass API. For example, the client devices that you want to add to the group are contained in a DeviceDefinitionVersion resource, which is associated with a DeviceDefinition resource. To add the devices to the group, the group version references the ARN of the DeviceDefinitionVersion.

The template includes parameters that let you specify the certificate ARNs for the core and device and the version ARN of the source Lambda function (which is an Amazon Lambda resource). It uses the Ref and GetAtt intrinsic functions to reference IDs, ARNs, and other attributes that are required to create Greengrass resources.

The template also defines two Amazon IoT devices (things), which represent the core and client device that are added to the Greengrass group.

After you create the stack with your Greengrass resources, you can use the Amazon CLI or the Amazon IoT console to deploy the group.

Note

The CommandToDeployGroup statement in the example shows how to output a complete create-deployment CLI command that you can use to deploy your group.

JSON
{ "AWSTemplateFormatVersion": "2010-09-09", "Description": "AWS IoT Greengrass example template that creates a group version with a core, device, function, logger, subscription, and resources.", "Parameters": { "CoreCertificateArn": { "Type": "String" }, "DeviceCertificateArn": { "Type": "String" }, "LambdaVersionArn": { "Type": "String" } }, "Resources": { "TestCore1": { "Type": "AWS::IoT::Thing", "Properties": { "ThingName": "TestCore1" } }, "TestCoreDefinition": { "Type": "AWS::Greengrass::CoreDefinition", "Properties": { "Name": "DemoTestCoreDefinition" } }, "TestCoreDefinitionVersion": { "Type": "AWS::Greengrass::CoreDefinitionVersion", "Properties": { "CoreDefinitionId": { "Ref": "TestCoreDefinition" }, "Cores": [ { "Id": "TestCore1", "CertificateArn": { "Ref": "CoreCertificateArn" }, "SyncShadow": "false", "ThingArn": { "Fn::Join": [ ":", [ "arn:aws:iot", { "Ref": "AWS::Region" }, { "Ref": "AWS::AccountId" }, "thing/TestCore1" ] ] } } ] } }, "TestClientDevice1": { "Type": "AWS::IoT::Thing", "Properties": { "ThingName": "TestClientDevice1" } }, "TestDeviceDefinition": { "Type": "AWS::Greengrass::DeviceDefinition", "Properties": { "Name": "DemoTestDeviceDefinition" } }, "TestDeviceDefinitionVersion": { "Type": "AWS::Greengrass::DeviceDefinitionVersion", "Properties": { "DeviceDefinitionId": { "Fn::GetAtt": [ "TestDeviceDefinition", "Id" ] }, "Devices": [ { "Id": "TestClientDevice1", "CertificateArn": { "Ref": "DeviceCertificateArn" }, "SyncShadow": "true", "ThingArn": { "Fn::Join": [ ":", [ "arn:aws:iot", { "Ref": "AWS::Region" }, { "Ref": "AWS::AccountId" }, "thing/TestClientDevice1" ] ] } } ] } }, "TestFunctionDefinition": { "Type": "AWS::Greengrass::FunctionDefinition", "Properties": { "Name": "DemoTestFunctionDefinition" } }, "TestFunctionDefinitionVersion": { "Type": "AWS::Greengrass::FunctionDefinitionVersion", "Properties": { "FunctionDefinitionId": { "Fn::GetAtt": [ "TestFunctionDefinition", "Id" ] }, "DefaultConfig": { "Execution": { "IsolationMode": "GreengrassContainer" } }, "Functions": [ { "Id": "TestLambda1", "FunctionArn": { "Ref": "LambdaVersionArn" }, "FunctionConfiguration": { "Pinned": "true", "Executable": "run.exe", "ExecArgs": "argument1", "MemorySize": "512", "Timeout": "2000", "EncodingType": "binary", "Environment": { "Variables": { "variable1": "value1" }, "ResourceAccessPolicies": [ { "ResourceId": "ResourceId1", "Permission": "ro" }, { "ResourceId": "ResourceId2", "Permission": "rw" } ], "AccessSysfs": "false", "Execution": { "IsolationMode": "GreengrassContainer", "RunAs": { "Uid": "1", "Gid": "10" } } } } } ] } }, "TestLoggerDefinition": { "Type": "AWS::Greengrass::LoggerDefinition", "Properties": { "Name": "DemoTestLoggerDefinition" } }, "TestLoggerDefinitionVersion": { "Type": "AWS::Greengrass::LoggerDefinitionVersion", "Properties": { "LoggerDefinitionId": { "Ref": "TestLoggerDefinition" }, "Loggers": [ { "Id": "TestLogger1", "Type": "AWSCloudWatch", "Component": "GreengrassSystem", "Level": "INFO" } ] } }, "TestResourceDefinition": { "Type": "AWS::Greengrass::ResourceDefinition", "Properties": { "Name": "DemoTestResourceDefinition" } }, "TestResourceDefinitionVersion": { "Type": "AWS::Greengrass::ResourceDefinitionVersion", "Properties": { "ResourceDefinitionId": { "Ref": "TestResourceDefinition" }, "Resources": [ { "Id": "ResourceId1", "Name": "LocalDeviceResource", "ResourceDataContainer": { "LocalDeviceResourceData": { "SourcePath": "/dev/TestSourcePath1", "GroupOwnerSetting": { "AutoAddGroupOwner": "false", "GroupOwner": "TestOwner" } } } }, { "Id": "ResourceId2", "Name": "LocalVolumeResourceData", "ResourceDataContainer": { "LocalVolumeResourceData": { "SourcePath": "/dev/TestSourcePath2", "DestinationPath": "/volumes/TestDestinationPath2", "GroupOwnerSetting": { "AutoAddGroupOwner": "false", "GroupOwner": "TestOwner" } } } } ] } }, "TestSubscriptionDefinition": { "Type": "AWS::Greengrass::SubscriptionDefinition", "Properties": { "Name": "DemoTestSubscriptionDefinition" } }, "TestSubscriptionDefinitionVersion": { "Type": "AWS::Greengrass::SubscriptionDefinitionVersion", "Properties": { "SubscriptionDefinitionId": { "Ref": "TestSubscriptionDefinition" }, "Subscriptions": [ { "Id": "TestSubscription1", "Source": { "Fn::Join": [ ":", [ "arn:aws:iot", { "Ref": "AWS::Region" }, { "Ref": "AWS::AccountId" }, "thing/TestClientDevice1" ] ] }, "Subject": "TestSubjectUpdated", "Target": { "Ref": "LambdaVersionArn" } } ] } }, "TestGroup": { "Type": "AWS::Greengrass::Group", "Properties": { "Name": "DemoTestGroupNewName", "RoleArn": { "Fn::Join": [ ":", [ "arn:aws:iam:", { "Ref": "AWS::AccountId" }, "role/TestUser" ] ] }, "InitialVersion": { "CoreDefinitionVersionArn": { "Ref": "TestCoreDefinitionVersion" }, "DeviceDefinitionVersionArn": { "Ref": "TestDeviceDefinitionVersion" }, "FunctionDefinitionVersionArn": { "Ref": "TestFunctionDefinitionVersion" }, "SubscriptionDefinitionVersionArn": { "Ref": "TestSubscriptionDefinitionVersion" }, "LoggerDefinitionVersionArn": { "Ref": "TestLoggerDefinitionVersion" }, "ResourceDefinitionVersionArn": { "Ref": "TestResourceDefinitionVersion" } }, "Tags": { "KeyName0": "value", "KeyName1": "value", "KeyName2": "value" } } } }, "Outputs": { "CommandToDeployGroup": { "Value": { "Fn::Join": [ " ", [ "groupVersion=$(cut -d'/' -f6 <<<", { "Fn::GetAtt": [ "TestGroup", "LatestVersionArn" ] }, ");", "aws --region", { "Ref": "AWS::Region" }, "greengrass create-deployment --group-id", { "Ref": "TestGroup" }, "--deployment-type NewDeployment --group-version-id", "$groupVersion" ] ] } } } }
YAML
AWSTemplateFormatVersion: 2010-09-09 Description: >- AWS IoT Greengrass example template that creates a group version with a core, device, function, logger, subscription, and resources. Parameters: CoreCertificateArn: Type: String DeviceCertificateArn: Type: String LambdaVersionArn: Type: String Resources: TestCore1: Type: 'AWS::IoT::Thing' Properties: ThingName: TestCore1 TestCoreDefinition: Type: 'AWS::Greengrass::CoreDefinition' Properties: Name: DemoTestCoreDefinition TestCoreDefinitionVersion: Type: 'AWS::Greengrass::CoreDefinitionVersion' Properties: CoreDefinitionId: !Ref TestCoreDefinition Cores: - Id: TestCore1 CertificateArn: !Ref CoreCertificateArn SyncShadow: 'false' ThingArn: !Join - ':' - - 'arn:aws:iot' - !Ref 'AWS::Region' - !Ref 'AWS::AccountId' - thing/TestCore1 TestClientDevice1: Type: 'AWS::IoT::Thing' Properties: ThingName: TestClientDevice1 TestDeviceDefinition: Type: 'AWS::Greengrass::DeviceDefinition' Properties: Name: DemoTestDeviceDefinition TestDeviceDefinitionVersion: Type: 'AWS::Greengrass::DeviceDefinitionVersion' Properties: DeviceDefinitionId: !GetAtt - TestDeviceDefinition - Id Devices: - Id: TestClientDevice1 CertificateArn: !Ref DeviceCertificateArn SyncShadow: 'true' ThingArn: !Join - ':' - - 'arn:aws:iot' - !Ref 'AWS::Region' - !Ref 'AWS::AccountId' - thing/TestClientDevice1 TestFunctionDefinition: Type: 'AWS::Greengrass::FunctionDefinition' Properties: Name: DemoTestFunctionDefinition TestFunctionDefinitionVersion: Type: 'AWS::Greengrass::FunctionDefinitionVersion' Properties: FunctionDefinitionId: !GetAtt - TestFunctionDefinition - Id DefaultConfig: Execution: IsolationMode: GreengrassContainer Functions: - Id: TestLambda1 FunctionArn: !Ref LambdaVersionArn FunctionConfiguration: Pinned: 'true' Executable: run.exe ExecArgs: argument1 MemorySize: '512' Timeout: '2000' EncodingType: binary Environment: Variables: variable1: value1 ResourceAccessPolicies: - ResourceId: ResourceId1 Permission: ro - ResourceId: ResourceId2 Permission: rw AccessSysfs: 'false' Execution: IsolationMode: GreengrassContainer RunAs: Uid: '1' Gid: '10' TestLoggerDefinition: Type: 'AWS::Greengrass::LoggerDefinition' Properties: Name: DemoTestLoggerDefinition TestLoggerDefinitionVersion: Type: 'AWS::Greengrass::LoggerDefinitionVersion' Properties: LoggerDefinitionId: !Ref TestLoggerDefinition Loggers: - Id: TestLogger1 Type: AWSCloudWatch Component: GreengrassSystem Level: INFO TestResourceDefinition: Type: 'AWS::Greengrass::ResourceDefinition' Properties: Name: DemoTestResourceDefinition TestResourceDefinitionVersion: Type: 'AWS::Greengrass::ResourceDefinitionVersion' Properties: ResourceDefinitionId: !Ref TestResourceDefinition Resources: - Id: ResourceId1 Name: LocalDeviceResource ResourceDataContainer: LocalDeviceResourceData: SourcePath: /dev/TestSourcePath1 GroupOwnerSetting: AutoAddGroupOwner: 'false' GroupOwner: TestOwner - Id: ResourceId2 Name: LocalVolumeResourceData ResourceDataContainer: LocalVolumeResourceData: SourcePath: /dev/TestSourcePath2 DestinationPath: /volumes/TestDestinationPath2 GroupOwnerSetting: AutoAddGroupOwner: 'false' GroupOwner: TestOwner TestSubscriptionDefinition: Type: 'AWS::Greengrass::SubscriptionDefinition' Properties: Name: DemoTestSubscriptionDefinition TestSubscriptionDefinitionVersion: Type: 'AWS::Greengrass::SubscriptionDefinitionVersion' Properties: SubscriptionDefinitionId: !Ref TestSubscriptionDefinition Subscriptions: - Id: TestSubscription1 Source: !Join - ':' - - 'arn:aws:iot' - !Ref 'AWS::Region' - !Ref 'AWS::AccountId' - thing/TestClientDevice1 Subject: TestSubjectUpdated Target: !Ref LambdaVersionArn TestGroup: Type: 'AWS::Greengrass::Group' Properties: Name: DemoTestGroupNewName RoleArn: !Join - ':' - - 'arn:aws:iam:' - !Ref 'AWS::AccountId' - role/TestUser InitialVersion: CoreDefinitionVersionArn: !Ref TestCoreDefinitionVersion DeviceDefinitionVersionArn: !Ref TestDeviceDefinitionVersion FunctionDefinitionVersionArn: !Ref TestFunctionDefinitionVersion SubscriptionDefinitionVersionArn: !Ref TestSubscriptionDefinitionVersion LoggerDefinitionVersionArn: !Ref TestLoggerDefinitionVersion ResourceDefinitionVersionArn: !Ref TestResourceDefinitionVersion Tags: KeyName0: value KeyName1: value KeyName2: value Outputs: CommandToDeployGroup: Value: !Join - ' ' - - groupVersion=$(cut -d'/' -f6 <<< - !GetAtt - TestGroup - LatestVersionArn - ); - aws --region - !Ref 'AWS::Region' - greengrass create-deployment --group-id - !Ref TestGroup - '--deployment-type NewDeployment --group-version-id' - $groupVersion

Supported Amazon Web Services Regions

Currently, you can create and manage Amazon IoT Greengrass resources only in the following Amazon Web Services Regions:

  • US East (Ohio)

  • US East (N. Virginia)

  • US West (Oregon)

  • Asia Pacific (Mumbai)

  • Asia Pacific (Seoul)

  • Asia Pacific (Singapore)

  • Asia Pacific (Sydney)

  • Asia Pacific (Tokyo)

  • China (Beijing)

  • Europe (Frankfurt)

  • Europe (Ireland)

  • Europe (London)

  • Amazon GovCloud (US-West)