] }
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\",
\"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.
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.
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. 519).
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.
{ "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
Install with fleet provisioning
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 --policy-arn:aws:iam::aws:policy/service-role/AWSIoTThingsRegistration
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.
Install with fleet provisioning
• 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",
"PolicyName": "GreengrassV2IoTThingPolicy"
},
"Type": "AWS::IoT::Policy"
},
"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
Install with fleet provisioning
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
NoteIf 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
}
Install with fleet provisioning