配置核心设备
设置脚本为一个核心设备创建 AWS IoT 身份,启动一个 Ubuntu 26.04 x86_64 EC2 实例,并通过 AWS Systems Manager 在其上安装经典 Greengrass 核心。它将创建的内容记录在 .greengrass-tutorial.env 中,绑定到您的账户、区域和前缀,因此其 cleanup 操作稍后会精确删除这些资源。
| 资源 | 名称 | 创建者 |
|---|---|---|
| IoT 物品组 | <prefix>-group | 脚本 |
| IoT 物品 | <prefix>-core | 脚本 |
| 令牌交换角色及其访问策略 | <prefix>-token-exchange、<prefix>-token-exchangeAccess | 脚本 |
| IoT 角色别名 | <prefix>-alias | 脚本 |
| 设备 IoT 策略 | <prefix>-device-policy | 脚本 |
| EC2 实例 | 标记为 Name=<prefix>-core | 脚本 |
| 设备证书和私钥 | 在实例上生成 | Nucleus 安装程序 |
| 角色别名的 IoT 策略 | GreengrassTESCertificatePolicy<prefix>-alias | Nucleus 安装程序 |
安装程序使用实例配置文件的临时凭证在实例上运行。设备私钥在实例上创建并保留在 /greengrass/v2 下。脚本通过 Systems Manager 发送的远程命令仅包含资源名称,因此没有密钥或凭证进入 Systems Manager 命令历史记录。
任务 1:创建实例配置文件
Section titled “任务 1:创建实例配置文件”脚本不会创建实例配置文件。您拥有它,因此您可以控制安装程序被允许执行的操作。其角色需要 AmazonSSMManagedInstanceCore,以便 Systems Manager 可以运行安装命令,以及安装程序的 --provision true 路径的临时策略。
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/AmazonSSMManagedInstanceCore临时安装程序策略遵循安装程序的最小 IAM 策略。CreateIoTResources 语句是官方的。IAM 语句比官方的 CreateTokenExchangeRole 语句更窄:脚本在安装程序运行之前创建令牌交换角色及其 <role>Access 策略,因此安装程序只读取它们,永远不需要 iam:CreateRole、iam:CreatePolicy 或 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"任务 4 在设备配置完成后再次删除 greengrass-installer-bootstrap。
任务 2:选择 Ubuntu 26.04 x86_64 镜像
Section titled “任务 2:选择 Ubuntu 26.04 x86_64 镜像”Canonical 将其当前镜像 ID 发布为公共 Systems Manager 参数。读取 Ubuntu 26.04 on amd64 的参数,然后在使用之前确认所有者、架构和名称:
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输出必须显示所有者 099720109477 (Canonical)、架构 x86_64 以及包含 ubuntu-resolute-26.04-amd64-server 的名称。脚本检查相同的三个值并拒绝任何其他镜像。
使用 Ubuntu 26.04 有两个原因。它附带 python3.14,这是生成的配方的 Run 步骤固定的解释器。它还将 sudo-rs 作为默认的 sudo,这可能会阻止 IPC 组件在 Nucleus 2.18.3 下启动,因为 IPC 环境丢失了。脚本安装 openjdk-21-jre-headless、unzip、python3.14 和经典的 sudo 包,该包提供 /usr/bin/sudo.ws,然后选择 /usr/bin/sudo.ws 作为 sudo 并在安装核心之前验证选择。在 Canonical 镜像上,sudo 和 sudo-rs 都是预安装的,因此替代方案切换是有效的步骤。请参阅组件故障排除说明。
任务 3:下载并运行设置脚本
Section titled “任务 3:下载并运行设置脚本”从此文档站点下载脚本,阅读它,然后从工作区根目录运行它:
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.sh相同的文件已签入存储库的 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"当区域没有默认 VPC 时,传递 --subnet-id <subnet-id>。传递 --instance-type 以更改默认的 t3.small。
脚本按顺序执行这些步骤,并在每个创建的资源后写入状态文件:
- 解析调用者身份,验证镜像,并检查实例配置文件是否存在。
- 检查上表中的资源是否都不存在。前缀下存在的物品组、物品、角色、策略或角色别名会在创建任何内容之前停止脚本。
- 创建物品组和物品、令牌交换角色及其访问策略、角色别名和设备 IoT 策略。IoT 策略是开发人员指南中的最小核心设备策略,加上
arn:aws:iot:<region>:<account-id>:topic/tutorial/greengrass/heartbeat上的iot:Publish。 - 使用实例配置文件和所需的 IMDSv2 启动实例,等待它向 Systems Manager 注册,并发送一个
AWS-RunShellScript命令,该命令安装先决条件、切换sudo、下载 Greengrass nucleus 2.18.3,并使用--provision true --setup-system-service true、上述物品、组、策略、角色和别名名称以及--component-default-user ggc_user:ggc_group运行安装程序。 - 轮询命令直到完成,然后记录安装程序附加到物品的证书,并等待核心设备出现在 Greengrass 中。
设置大约需要十分钟。完成后,将记录的值加载到您的 shell 中,并将状态文件保留在 Git 之外:
source .greengrass-tutorial.envecho .greengrass-tutorial.env >> .gitignore状态文件导出 TUTORIAL_THING_NAME、TUTORIAL_THING_GROUP_ARN、TUTORIAL_TOKEN_EXCHANGE_ROLE_ARN、TUTORIAL_INSTANCE_ID、TUTORIAL_CERTIFICATE_ARN 以及它绑定到的身份。模块 3 将其中两个传递给 CDK 堆栈。
任务 4:删除临时安装程序权限
Section titled “任务 4:删除临时安装程序权限”安装程序已完成。删除引导策略,以便实例仅保留 Systems Manager 访问权限:
aws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" iam delete-role-policy \ --role-name "${TUTORIAL_PREFIX}-instance" \ --policy-name greengrass-installer-bootstrap任务 5:检查设备
Section titled “任务 5:检查设备”核心在首次启动时注册核心设备。从云端确认它:
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}'期望 HEALTHY、linux 和 amd64。要读取实例上的日志,请使用参数文件发送 Systems Manager 命令。第一行是 shebang,AWS-RunShellScript 会遵守它:
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 text模块 3 使用相同的模式来读取组件自己的日志。
继续部署、观察和更新。