This AWS Cloud Development Kit (CDK v2) application deploys a heterogeneous test fleet of AWS IoT Greengrass core devices as instances in EC2. The aim is to provide a fleet of Greengrass devices with disparate operating systems and machine architectures to support testing of Greengrass components.
The fleet of instances deployed is as follows.
| Operating System | Architecture | Type |
|---|---|---|
| Amazon Linux 2023 | x86_64 (amd64) | t3.small |
| Amazon Linux 2023 | aarch64 (arm64) | t4g.small |
| Ubuntu Server 22.04 LTS | x86_64 (amd64) | t3.small |
| Ubuntu Server 22.04 LTS | aarch64 (arm64) | t4g.small |
| Ubuntu Server 20.04 LTS | x86_64 (amd64) | t3.small |
| Ubuntu Server 20.04 LTS | aarch64 (arm64) | t4g.small |
| Windows Server 2022 | x86_64 (amd64) | t3.small |
| Windows Server 2019 | x86_64 (amd64) | t3.small |
For each instance, Greengrass is installed with automatic provisioning via instance user data.
Each Linux instance has an 8GB EBS volume and each Windows instance has a 30GB EBS volume.
To debug your Greengrass components, it's necessary to be able to access Greengrass logs on each core device. Amazon EC2 offers many connection options, including:
| Linux instances | Windows instances |
|---|---|
| AWS Systems Manager Session Manager | AWS Systems Manager Session Manager |
| SSH | RDP |
| EC2 Instance Connect | Fleet Manager |
By default, each instance in the Greengrass EC2 Device Farm is only accessible using AWS Systems Manager Session Manager.
However, each instance is deployed with a public IP address and with a shared EC2 key pair named GreengrassEC2DeviceFarm. The CDK application outputs instructions on how to download the private key.
Accordingly, if you choose to open the appropriate ports, Linux instances can be accessed using SSH (or EC2 Instance Connect) and Windows instances can be accessed using RDP (or Fleet Manager).
Linux instances are deployed in a security group named GreengrassEC2DeviceFarmLinuxSG. Open inbound port 22 to enable SSH client access (or EC2 Instance Connect).
Windows instances are deployed in a security group named GreengrassEC2DeviceFarmWindowsSG. Open inbound port 3389 to enable RDP client access (or Fleet Manager).
Costs vary per region and are subject to change. Please consult latest pricing information for your region. Please consider to stop instances, when not actively using them, to minimize costs.
How to deploy the fleet.
Follow the Getting started with the AWS SDK guide (for Typescript) to install CDK and bootstrap your environment.
Install required packages.
npm install
Compile TypeScript to JS.
npm run build
Uses the Jest framework.
npm run test
Deploy the fleet, to create the instances and create the Greengrass core devices in AWS IoT.
cdk deploy
The Greengrass core devices take a few minutes to be provisioned in AWS IoT Core after the CDK application is deployed. The Windows instances, and associated Greengrass core devices, take several minutes longer to be created than the Linux instances.
Undeploy the fleet.
cdk destroy
The application creates an AWS IoT static thing group named GreengrassEC2DeviceFarm and a Greengrass deployment named Deployment for GreengrassEC2DeviceFarm. You can add your components to this deployment to test them across the range of operating systems and architectures supported by the fleet.
The application creates a Greengrass core device IAM role named GreengrassEC2DeviceFarmTokenExchangeRole with attached IAM policy GreengrassEC2DeviceFarmTokenExchangeRoleAccess. All instances use this role through a role alias named GreengrassEC2DeviceFarmTokenExchangeRoleAlias.
This role does not allow access to S3 buckets for component artifacts by default. GreengrassEC2DeviceFarmTokenExchangeRoleAccess contains a placeholder policy statement as follows:
{
"Effect": "Allow",
"Action": [
"s3:GetObject"
],
"Resource": "arn:aws:s3:::DOC-EXAMPLE-BUCKET/*"
}
To deploy your custom component, please replace DOC-EXAMPLE-BUCKET with the name of the bucket your component uses to store its artifacts.
If your components need additional permissions (for example, allowing access to secrets in Secret Manager), please add to or adjust the policies attached to this role.
The Linux instances in the fleet are deployed with all requirements to run a Docker container, with both docker and docker-compose installed. Therefore it's possible to deploy and test container-based components on those instances. The Windows instances do no support Docker. Accordingly to test container-based components, it's advisable to create another thing group that includes just the Linux instances, and create another deployment that targets just that group.
It may also be necessary to add to or adjust the policies attached to the GreengrassEC2DeviceFarmTokenExchangeRole core device role, to allow access to containers in Amazon ECR or Amazon S3.
The application creates a security group named GreengrassEC2DeviceFarmLinuxSG for the Linux instances and GreengrassEC2DeviceFarmWindowsSG for the Windows instances. If you install a component that requires particular open ports, you should open the appropriate inbound ports in these security groups.
The Greengrass automatic provisioning creates the following resources:
- An AWS IoT Thing for each instance.
- An AWS IoT X.509 certificate for each thing as the thing principal.
- A Greengrass core device for each instance.
- An AWS IoT static thing group named GreengrassEC2DeviceFarm.
- A Greengrass deployment for the thing group.
- Two AWS IoT thing policies: GreengrassEC2DeviceFarm and GreengrassTESCertificatePolicyGreengrassEC2DeviceFarmTokenExchangeRoleAlias.
- A Greengrass token exchange role alias named GreengrassEC2DeviceFarmTokenExchangeRoleAlias.
As these are not created by the CDK application, the cdk destroy operation does not delete them. The clean_iot.py script is provided to remove these resources after the CDK application has been destroyed.
Should any of the Greengrass core devices fail to be created successfully in AWS IoT Core, please connect to the instance and examine the AWS EC2 instance user data logs for details.
/var/log/cloud-init-output.log
C:\ProgramData\Amazon\EC2-Windows\Launch\Log\UserdataExecution.log
Or
C:\ProgramData\Amazon\EC2Launch\log\agent.log