Provision the core device
The setup script creates the AWS IoT identity for one core device, launches an Ubuntu 26.04 x86_64 EC2 instance, and installs the classic Greengrass nucleus on it through AWS Systems Manager. It records what it created in .greengrass-tutorial.env, bound to your account, Region and prefix, so its cleanup operation deletes exactly those resources later.
| Resource | Name | Created by |
|---|---|---|
| IoT thing group | <prefix>-group | Script |
| IoT thing | <prefix>-core | Script |
| Token exchange role and its access policy | <prefix>-token-exchange, <prefix>-token-exchangeAccess | Script |
| IoT role alias | <prefix>-alias | Script |
| Device IoT policy | <prefix>-device-policy | Script |
| EC2 instance | Tagged Name=<prefix>-core | Script |
| Device certificate and private key | Generated on the instance | Nucleus installer |
| IoT policy for the role alias | GreengrassTESCertificatePolicy<prefix>-alias | Nucleus installer |
The installer runs on the instance with the instance profile’s temporary credentials. The device private key is created on the instance and stays under /greengrass/v2. The remote command that the script sends through Systems Manager contains resource names only, so no key or credential enters the Systems Manager command history.
Task 1: Create the instance profile
Section titled “Task 1: Create the instance profile”The script does not create the instance profile. You own it, so you control what the installer is allowed to do. Its role needs AmazonSSMManagedInstanceCore, so Systems Manager can run the install command, plus a temporary policy for the installer’s --provision true path.
export TUTORIAL_ACCOUNT_ID=$(aws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" \ sts get-caller-identity --query Account --output text)
cat > /tmp/greengrass-tutorial-ec2-trust.json <<'EOF'{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "ec2.amazonaws.com" }, "Action": "sts:AssumeRole" } ]}EOF
aws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" iam create-role \ --role-name "${TUTORIAL_PREFIX}-instance" \ --assume-role-policy-document file:///tmp/greengrass-tutorial-ec2-trust.jsonaws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" iam attach-role-policy \ --role-name "${TUTORIAL_PREFIX}-instance" \ --policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCoreThe temporary installer policy follows the minimal IAM policy for the installer. The CreateIoTResources statement is the official one. The IAM statement is narrower than the official CreateTokenExchangeRole statement: the script creates the token exchange role and its <role>Access policy before the installer runs, so the installer only reads them and never needs iam:CreateRole, iam:CreatePolicy or iam:AttachRolePolicy.
cat > /tmp/greengrass-tutorial-installer.json <<EOF{ "Version": "2012-10-17", "Statement": [ { "Sid": "ReuseTokenExchangeRole", "Effect": "Allow", "Action": ["iam:GetRole", "iam:PassRole", "iam:GetPolicy"], "Resource": [ "arn:aws:iam::${TUTORIAL_ACCOUNT_ID}:role/${TUTORIAL_PREFIX}-token-exchange", "arn:aws:iam::${TUTORIAL_ACCOUNT_ID}:policy/${TUTORIAL_PREFIX}-token-exchangeAccess", "arn:aws:iam::aws:policy/${TUTORIAL_PREFIX}-token-exchangeAccess" ] }, { "Sid": "CreateIoTResources", "Effect": "Allow", "Action": [ "iot:AddThingToThingGroup", "iot:AttachPolicy", "iot:AttachThingPrincipal", "iot:CreateKeysAndCertificate", "iot:CreatePolicy", "iot:CreateRoleAlias", "iot:CreateThing", "iot:CreateThingGroup", "iot:DescribeEndpoint", "iot:DescribeRoleAlias", "iot:DescribeThingGroup", "iot:GetPolicy" ], "Resource": "*" } ]}EOF
aws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" iam put-role-policy \ --role-name "${TUTORIAL_PREFIX}-instance" \ --policy-name greengrass-installer-bootstrap \ --policy-document file:///tmp/greengrass-tutorial-installer.jsonaws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" iam create-instance-profile \ --instance-profile-name "${TUTORIAL_PREFIX}-instance"aws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" iam add-role-to-instance-profile \ --instance-profile-name "${TUTORIAL_PREFIX}-instance" \ --role-name "${TUTORIAL_PREFIX}-instance"Task 4 removes greengrass-installer-bootstrap again once the device is provisioned.
Task 2: Select the Ubuntu 26.04 x86_64 image
Section titled “Task 2: Select the Ubuntu 26.04 x86_64 image”Canonical publishes its current image IDs as public Systems Manager parameters. Read the one for Ubuntu 26.04 on amd64, then confirm the owner, architecture and name before you use it:
export TUTORIAL_AMI_ID=$(aws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" ssm get-parameter \ --name /aws/service/canonical/ubuntu/server/26.04/stable/current/amd64/hvm/ebs-gp3/ami-id \ --query Parameter.Value --output text)
aws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" ec2 describe-images \ --image-ids "$TUTORIAL_AMI_ID" \ --query 'Images[0].[OwnerId,Architecture,Name]' --output textThe output must show owner 099720109477 (Canonical), architecture x86_64, and a name containing ubuntu-resolute-26.04-amd64-server. The script checks the same three values and refuses any other image.
Ubuntu 26.04 is used for two reasons. It ships python3.14, which is the interpreter the generated recipe’s Run step pins. It also ships sudo-rs as the default sudo, which can prevent IPC components from starting under Nucleus 2.18.3 because the IPC environment is lost. The script installs openjdk-21-jre-headless, unzip, python3.14 and the classic sudo package, which provides /usr/bin/sudo.ws, then selects /usr/bin/sudo.ws as sudo and verifies the selection before it installs the nucleus. On the Canonical image both sudo and sudo-rs are preinstalled, so the alternatives switch is the effective step. See the component troubleshooting notes.
Task 3: Download and run the setup script
Section titled “Task 3: Download and run the setup script”Download the script from this documentation site, read it, then run it from the workspace root:
curl -fsSLo setup-greengrass-tutorial.sh https://awslabs.github.io/nx-plugin-for-aws/greengrass/setup-tutorial.shchmod +x setup-greengrass-tutorial.shless setup-greengrass-tutorial.shThe same file is checked into the repository at docs/public/greengrass/setup-tutorial.sh.
./setup-greengrass-tutorial.sh setup \ --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" --prefix "$TUTORIAL_PREFIX" \ --ami-id "$TUTORIAL_AMI_ID" --instance-profile "${TUTORIAL_PREFIX}-instance"Pass --subnet-id <subnet-id> when the Region has no default VPC. Pass --instance-type to change the default t3.small.
The script performs these steps in order, and writes the state file after each created resource:
- Resolves the caller identity, validates the image, and checks that the instance profile exists.
- Checks that none of the resources in the table above exist yet. An existing thing group, thing, role, policy or role alias under the prefix stops the script before it creates anything.
- Creates the thing group and thing, the token exchange role with its access policy, the role alias, and the device IoT policy. The IoT policy is the minimal core device policy from the developer guide, plus
iot:Publishonarn:aws:iot:<region>:<account-id>:topic/tutorial/greengrass/heartbeat. - Launches the instance with the instance profile and IMDSv2 required, waits for it to register with Systems Manager, and sends one
AWS-RunShellScriptcommand that installs the prerequisites, switchessudo, downloads Greengrass nucleus 2.18.3, and runs the installer with--provision true --setup-system-service true, the thing, group, policy, role and alias names above, and--component-default-user ggc_user:ggc_group. - Polls the command until it finishes, then records the certificate the installer attached to the thing and waits for the core device to appear in Greengrass.
Setup takes about ten minutes. When it finishes, load the recorded values into your shell and keep the state file out of Git:
source .greengrass-tutorial.envecho .greengrass-tutorial.env >> .gitignoreThe state file exports TUTORIAL_THING_NAME, TUTORIAL_THING_GROUP_ARN, TUTORIAL_TOKEN_EXCHANGE_ROLE_ARN, TUTORIAL_INSTANCE_ID, TUTORIAL_CERTIFICATE_ARN and the identity it is bound to. Module 3 passes two of them to the CDK stack.
Task 4: Remove the temporary installer permissions
Section titled “Task 4: Remove the temporary installer permissions”The installer has finished. Remove the bootstrap policy so the instance keeps Systems Manager access only:
aws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" iam delete-role-policy \ --role-name "${TUTORIAL_PREFIX}-instance" \ --policy-name greengrass-installer-bootstrapTask 5: Check the device
Section titled “Task 5: Check the device”The nucleus registers the core device on its first start. Confirm it from the cloud:
aws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" greengrassv2 get-core-device \ --core-device-thing-name "$TUTORIAL_THING_NAME" \ --query '{status: status, coreVersion: coreVersion, platform: platform, architecture: architecture}'Expect HEALTHY, linux, and amd64. To read a log on the instance, send a Systems Manager command with a parameters file. The first line is a shebang, which AWS-RunShellScript honours:
cat > /tmp/greengrass-tutorial-command.json <<'EOF'{ "commands": ["#!/bin/bash", "tail -n 20 /greengrass/v2/logs/greengrass.log"] }EOF
TUTORIAL_COMMAND_ID=$(aws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" ssm send-command \ --instance-ids "$TUTORIAL_INSTANCE_ID" --document-name AWS-RunShellScript \ --parameters file:///tmp/greengrass-tutorial-command.json \ --query Command.CommandId --output text)sleep 5aws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" ssm get-command-invocation \ --command-id "$TUTORIAL_COMMAND_ID" --instance-id "$TUTORIAL_INSTANCE_ID" \ --query StandardOutputContent --output textModule 3 uses the same pattern to read the component’s own log.
Continue with Deploy, observe and update.