Develop custom provisioning plugins - Amazon IoT Greengrass
RequirementsImplement the DeviceIdentityInterface interface
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).

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. The Amazon IoT Greengrass Core software installer uses this provisioning configuration to configure the Amazon 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 Amazon 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.

Note

The Amazon IoT fleet provisioning plugin implements the DeviceIdentityInterface to use fleet provisioning during installation. The fleet provisioning plugin is open source, so you can explore its source code to see an example of how to use the provisioning plugin interface. For more information, see the Amazon IoT fleet provisioning plugin on GitHub.

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.

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 Amazon IoT Greengrass Core software, which contains the Greengrass nucleus JAR. You can download the latest version of the Amazon IoT Greengrass Core software from the following location:

      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.

      <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.0-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".
}
   
com.aws.greengrass.provisioning.exceptions.RetryableProvisioningException {}

Each configuration value in the SystemConfiguration and NucleusConfiguration is required to install the Amazon 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 Amazon 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.