Configure the Amazon IoT fleet provisioning plugin - 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 (PDF).

Configure the Amazon IoT fleet provisioning plugin

The Amazon IoT fleet provisioning plugin provides the following configuration parameters that you can customize when you install the Amazon IoT Greengrass Core software with fleet provisioning.

rootPath

The path to the folder to use as the root for the Amazon IoT Greengrass Core software.

awsRegion

The Amazon Web Services Region that the fleet provisioning plugin uses to provision Amazon resources.

iotDataEndpoint

The Amazon IoT data endpoint for your Amazon Web Services account.

iotCredentialEndpoint

The Amazon IoT credentials endpoint for your Amazon Web Services account.

iotRoleAlias

The Amazon IoT role alias that points to a token exchange IAM role. The Amazon IoT credentials provider assumes this role to allow the Greengrass core device to interact with Amazon services. For more information, see Authorize core devices to interact with Amazon services.

provisioningTemplate

The Amazon IoT fleet provisioning template to use to provision Amazon resources. This template must specify the following:

  • An Amazon IoT thing resource. You can specify a list of existing thing groups to deploy components to each device when it comes online.

  • An Amazon IoT policy resource. This resource can define one of the following properties:

    • The name of an existing Amazon IoT policy. If you choose this option, the core devices that you create from this template use the same Amazon IoT policy, and you can manage their permissions as a fleet.

    • An Amazon IoT policy document. If you choose this option, each core device that you create from this template uses a unique Amazon IoT policy, and you can manage permissions for each individual core device.

  • An Amazon 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 Amazon IoT Developer Guide.

For more information, see Provisioning templates in the Amazon 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 Amazon 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 Amazon 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 Amazon IoT in the Amazon IoT Core Developer Guide.

To help you better manage the number of devices, and which devices, that register themselves in your Amazon Web Services account, you can specify a pre-provisioning hook when you create a fleet provisioning template. A pre-provisioning hook is an Amazon 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 Amazon 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 Amazon 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 Amazon 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. To use an HTTPS proxy, you must use version 1.1.0 or later of the fleet provisioning plugin.

  • scheme – The scheme, which must be http or https.

    Important

    Greengrass core devices must run Greengrass nucleus 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.

  • 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.

csrPath

(Optional) The path to the certificate signing request (CSR) file to use to create the device certificate from a CSR. For more information, see Provisioning by claim in the Amazon IoT Core developer guide.

csrPrivateKeyPath

(Optional, required if csrPath is declared) The path to the private key used to generate the CSR. The private key must have been used to generate the CSR. For more information, see Provisioning by claim in the Amazon IoT Core developer guide.