Pular para o conteúdo

Provisionar o dispositivo central

O script de configuração cria a identidade AWS IoT para um dispositivo central, inicia uma instância EC2 Ubuntu 26.04 x86_64 e instala o núcleo Greengrass clássico nela através do AWS Systems Manager. Ele registra o que criou em .greengrass-tutorial.env, vinculado à sua conta, Região e prefixo, para que sua operação cleanup exclua exatamente esses recursos posteriormente.

RecursoNomeCriado por
Grupo de coisas IoT<prefix>-groupScript
Coisa IoT<prefix>-coreScript
Função de troca de token e sua política de acesso<prefix>-token-exchange, <prefix>-token-exchangeAccessScript
Alias de função IoT<prefix>-aliasScript
Política IoT do dispositivo<prefix>-device-policyScript
Instância EC2Marcada Name=<prefix>-coreScript
Certificado do dispositivo e chave privadaGerado na instânciaInstalador do Nucleus
Política IoT para o alias de funçãoGreengrassTESCertificatePolicy<prefix>-aliasInstalador do Nucleus

O instalador é executado na instância com as credenciais temporárias do perfil da instância. A chave privada do dispositivo é criada na instância e permanece em /greengrass/v2. O comando remoto que o script envia através do Systems Manager contém apenas nomes de recursos, portanto nenhuma chave ou credencial entra no histórico de comandos do Systems Manager.

O script não cria o perfil de instância. Você é o proprietário dele, então você controla o que o instalador tem permissão para fazer. Sua função precisa de AmazonSSMManagedInstanceCore, para que o Systems Manager possa executar o comando de instalação, além de uma política temporária para o caminho --provision true do instalador.

Janela do terminal
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

A política temporária do instalador segue a política IAM mínima para o instalador. A declaração CreateIoTResources é a oficial. A declaração IAM é mais restrita do que a declaração oficial CreateTokenExchangeRole: o script cria a função de troca de token e sua política <role>Access antes que o instalador seja executado, então o instalador apenas as lê e nunca precisa de iam:CreateRole, iam:CreatePolicy ou iam:AttachRolePolicy.

Janela do terminal
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"

A Tarefa 4 remove greengrass-installer-bootstrap novamente assim que o dispositivo for provisionado.

A Canonical publica seus IDs de imagem atuais como parâmetros públicos do Systems Manager. Leia o parâmetro para Ubuntu 26.04 em amd64 e, em seguida, confirme o proprietário, arquitetura e nome antes de usá-lo:

Janela do terminal
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

A saída deve mostrar o proprietário 099720109477 (Canonical), arquitetura x86_64 e um nome contendo ubuntu-resolute-26.04-amd64-server. O script verifica os mesmos três valores e recusa qualquer outra imagem.

O Ubuntu 26.04 é usado por dois motivos. Ele vem com python3.14, que é o interpretador que a etapa Run da receita gerada fixa. Ele também vem com sudo-rs como o sudo padrão, o que pode impedir que componentes IPC iniciem sob o Nucleus 2.18.3 porque o ambiente IPC é perdido. O script instala openjdk-21-jre-headless, unzip, python3.14 e o pacote sudo clássico, que fornece /usr/bin/sudo.ws, em seguida seleciona /usr/bin/sudo.ws como sudo e verifica a seleção antes de instalar o núcleo. Na imagem Canonical, tanto sudo quanto sudo-rs são pré-instalados, então a alternância de alternativas é a etapa efetiva. Consulte as notas de solução de problemas do componente.

Tarefa 3: Baixar e executar o script de configuração

Seção intitulada “Tarefa 3: Baixar e executar o script de configuração”

Baixe o script deste site de documentação, leia-o e execute-o a partir da raiz do workspace:

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

O mesmo arquivo está registrado no repositório em docs/public/greengrass/setup-tutorial.sh.

Janela do terminal
./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"

Passe --subnet-id <subnet-id> quando a Região não tiver VPC padrão. Passe --instance-type para alterar o padrão t3.small.

O script executa estas etapas em ordem e grava o arquivo de estado após cada recurso criado:

  1. Resolve a identidade do chamador, valida a imagem e verifica se o perfil de instância existe.
  2. Verifica se nenhum dos recursos na tabela acima existe ainda. Um grupo de coisas, coisa, função, política ou alias de função existente sob o prefixo interrompe o script antes que ele crie qualquer coisa.
  3. Cria o grupo de coisas e a coisa, a função de troca de token com sua política de acesso, o alias de função e a política IoT do dispositivo. A política IoT é a política mínima do dispositivo central do guia do desenvolvedor, mais iot:Publish em arn:aws:iot:<region>:<account-id>:topic/tutorial/greengrass/heartbeat.
  4. Inicia a instância com o perfil de instância e IMDSv2 obrigatório, aguarda que ela se registre no Systems Manager e envia um comando AWS-RunShellScript que instala os pré-requisitos, alterna o sudo, baixa o Greengrass nucleus 2.18.3 e executa o instalador com --provision true --setup-system-service true, os nomes de coisa, grupo, política, função e alias acima, e --component-default-user ggc_user:ggc_group.
  5. Pesquisa o comando até que ele termine, em seguida registra o certificado que o instalador anexou à coisa e aguarda que o dispositivo central apareça no Greengrass.

A configuração leva cerca de dez minutos. Quando terminar, carregue os valores registrados em seu shell e mantenha o arquivo de estado fora do Git:

Janela do terminal
source .greengrass-tutorial.env
echo .greengrass-tutorial.env >> .gitignore

O arquivo de estado exporta TUTORIAL_THING_NAME, TUTORIAL_THING_GROUP_ARN, TUTORIAL_TOKEN_EXCHANGE_ROLE_ARN, TUTORIAL_INSTANCE_ID, TUTORIAL_CERTIFICATE_ARN e a identidade à qual está vinculado. O Módulo 3 passa dois deles para a pilha CDK.

Tarefa 4: Remover as permissões temporárias do instalador

Seção intitulada “Tarefa 4: Remover as permissões temporárias do instalador”

O instalador terminou. Remova a política de bootstrap para que a instância mantenha apenas o acesso ao Systems Manager:

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

O núcleo registra o dispositivo central em sua primeira inicialização. Confirme-o a partir da nuvem:

Janela do terminal
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}'

Espere HEALTHY, linux e amd64. Para ler um log na instância, envie um comando do Systems Manager com um arquivo de parâmetros. A primeira linha é um shebang, que AWS-RunShellScript honra:

Janela do terminal
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

O Módulo 3 usa o mesmo padrão para ler o log do próprio componente.

Continue com Implantar, observar e atualizar.