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. 134).
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.
<project ...>
...
<repositories>
<repository>
<id>greengrass-common</id>
<name>greengrass common</name>
<url>https://d2jrmugq4soldf.cloudfront.net/snapshots</url>
</repository>
</repositories>
Install with custom provisioning
...
<dependencies>
<dependency>
</dependencies>
</project>
The DeviceIdentityInterface interface
The com.aws.greengrass.provisioning.DeviceIdentityInterface interface has the following shape.
NoteYou 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 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
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.
NoteThis 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.
NoteThe thing name can't contain colon (:) characters.
You must specify --provision true to apply this argument.
Default: GreengrassV2IotThing_ plus a random UUID.
-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.
NoteThe thing group name can't contain colon (:) characters.
Installer arguments
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. 189).
(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. 830).
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. 843).
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. 165).
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.
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: