Skip to content

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.

ResourceNameCreated by
IoT thing group<prefix>-groupScript
IoT thing<prefix>-coreScript
Token exchange role and its access policy<prefix>-token-exchange, <prefix>-token-exchangeAccessScript
IoT role alias<prefix>-aliasScript
Device IoT policy<prefix>-device-policyScript
EC2 instanceTagged Name=<prefix>-coreScript
Device certificate and private keyGenerated on the instanceNucleus installer
IoT policy for the role aliasGreengrassTESCertificatePolicy<prefix>-aliasNucleus 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.

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.

Terminal window
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.json
aws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" iam attach-role-policy \
--role-name "${TUTORIAL_PREFIX}-instance" \
--policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore

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

Terminal window
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.json
aws --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:

Terminal window
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 text

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

Download the script from this documentation site, read it, then run it from the workspace root:

Terminal window
curl -fsSLo setup-greengrass-tutorial.sh https://awslabs.github.io/nx-plugin-for-aws/greengrass/setup-tutorial.sh
chmod +x setup-greengrass-tutorial.sh
less setup-greengrass-tutorial.sh

The same file is checked into the repository at docs/public/greengrass/setup-tutorial.sh.

Terminal window
./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:

  1. Resolves the caller identity, validates the image, and checks that the instance profile exists.
  2. 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.
  3. 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:Publish on arn:aws:iot:<region>:<account-id>:topic/tutorial/greengrass/heartbeat.
  4. Launches the instance with the instance profile and IMDSv2 required, waits for it to register with Systems Manager, and sends one AWS-RunShellScript command that installs the prerequisites, switches sudo, 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.
  5. 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:

Terminal window
source .greengrass-tutorial.env
echo .greengrass-tutorial.env >> .gitignore

The 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:

Terminal window
aws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" iam delete-role-policy \
--role-name "${TUTORIAL_PREFIX}-instance" \
--policy-name greengrass-installer-bootstrap

The nucleus registers the core device on its first start. Confirm it from the cloud:

Terminal window
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:

Terminal window
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 5
aws --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 text

Module 3 uses the same pattern to read the component’s own log.

Continue with Deploy, observe and update.