AWS IoT Greengrass Version 1 entrou na fase de vida útil prolongada em 30 de junho de 2023. Para obter mais informações, consulte política de manutenção do AWS IoT Greengrass V1. Após essa data, AWS IoT Greengrass V1 não lançaremos atualizações que forneçam recursos, aprimoramentos, correções de erros ou patches de segurança. Os dispositivos que funcionam AWS IoT Greengrass V1 não serão interrompidos e continuarão operando e se conectando à nuvem. É altamente recomendável que você migre para AWS IoT Greengrass Version 2, o que adiciona novos recursos significativos e suporte para plataformas adicionais.
As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
Atualizações OTA do software do AWS IoT Greengrass Core
O pacote de software de núcleo do AWS IoT Greengrass inclui um atendente de atualização que pode executar atualizações OTA (over-the-air) do software do AWS IoT Greengrass. Você pode usar atualizações OTA para instalar a versão mais recente do software de núcleo do AWS IoT Greengrass ou do software do atendente de atualizações OTA em um ou mais núcleos. Com as atualizações OTA, seus dispositivos principais não precisam estar fisicamente presentes.
É recomendável usar atualizações OTA quando possível. Elas fornecem um mecanismo que você pode usar para rastrear o status da atualização e o histórico de atualizações. Se ocorrer uma atualização com falha, o atendente de atualizações OTA reverterá para a versão anterior do software.
nota
Não haverá suporte para as atualizações OTA se você usar apt
para instalar o software de núcleo do AWS IoT Greengrass. Para essas instalações, é recomendável usar apt
para atualizar o software. Para obter mais informações, consulte Instalar o software do AWS IoT Greengrass Core de um repositório do APT.
As atualizações OTA são mais eficientes para:
-
Corrigir vulnerabilidades de segurança.
-
Resolver problemas de estabilidade do software.
-
Implantar atributos novos ou melhorados.
Esse atributo se integra aos Trabalhos do AWS IoT.
Requisitos
Os seguintes requisitos se aplicam às atualizações OTA do software do AWS IoT Greengrass.
-
O núcleo do Greengrass deve ter pelo menos 400 MB de espaço em disco disponível no armazenamento local. O atendente de atualizações OTA requer cerca de três vezes o requisito de uso de tempo de execução do software de núcleo do AWS IoT Greengrass. Para obter mais informações, consulte Cotas de serviço para o núcleo do Greengrass no Referência geral da Amazon Web Services.
-
O núcleo do Greengrass deve ter uma conexão com a Nuvem AWS.
-
O núcleo do Greengrass deve ser configurado corretamente e provisionado com certificados e chaves para autenticação com o AWS IoT Core e o AWS IoT Greengrass. Para obter mais informações, consulte Certificados X.509.
-
O núcleo do Greengrass não pode ser configurado para usar um proxy de rede.
nota
Desde o AWS IoT Greengrass v1.9.3, as atualizações OTA são compatíveis em núcleos que configuram o tráfego MQTT para usar a porta 443 em vez da porta padrão 8883. No entanto, o atendente de atualizações OTA não oferece suporte a atualizações por meio de um proxy de rede. Para obter mais informações, consulte Conectar-se à porta 443 ou por meio de um proxy de rede.
-
A inicialização confiável não pode ser habilitada na partição que contém o software de núcleo do AWS IoT Greengrass.
nota
Você pode instalar e executar o software de núcleo do AWS IoT Greengrass em uma partição que tenha inicialização confiável habilitada, mas as atualizações OTA não serão compatíveis.
-
O AWS IoT Greengrass deve ter permissões de leitura/gravação na partição que contém o software de núcleo do AWS IoT Greengrass.
-
Ao usar um sistema init para gerenciar o núcleo do Greengrass, você deve configurar as atualizações OTA para se integrarem ao sistema init. Para obter mais informações, consulte Integração com sistemas Init.
-
Crie uma função usada para pré-assinar os URLs do Amazon S3 para artefatos de atualização do software do AWS IoT Greengrass. Essa função de assinante do permite que AWS IoT Core acesse artefatos de atualização de software armazenados no Amazon S3 em seu nome. Para obter mais informações, consulte Permissões do IAM para atualizações OTA.
Permissões do IAM para atualizações OTA
Quando o AWS IoT Greengrass libera uma nova versão do software do núcleo do AWS IoT Greengrass, o AWS IoT Greengrass atualiza os artefatos de software armazenados no Amazon S3 que são usados para a atualização OTA.
Sua Conta da AWS deve incluir uma função de assinante de URL do Amazon S3 que possa ser usada para acessar esses artefatos. A função deve ter uma política de permissões que permita a ação s3:GetObject
nos buckets nas Região da AWSs de destino. A função também deve ter uma política de confiança que permita que o iot.amazonaws.com
assuma a função como uma entidade confiável.
- Política de permissões
-
Para permissões de função, você pode usar a política gerenciada pela AWS ou criar uma política personalizada.
-
Usar a política gerenciada pela AWS
A política gerenciada GreengrassOTAUpdateArtifactAccess
é fornecida pelo AWS IoT Greengrass. Use essa política se desejar permitir o acesso em todas as regiões atuais e futuras da Amazon Web Services compatíveis com o AWS IoT Greengrass. -
Crie uma política personalizada
Você deve criar uma política personalizada se quiser especificar explicitamente as regiões da Amazon Web Services em que seus núcleos estão implantados. A política de exemplo a seguir concede acesso a atualizações de software do AWS IoT Greengrass em seis regiões.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowAccessToGreengrassOTAUpdateArtifacts", "Effect": "Allow", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::us-east-1-greengrass-updates/*", "arn:aws:s3:::us-west-2-greengrass-updates/*", "arn:aws:s3:::ap-northeast-1-greengrass-updates/*", "arn:aws:s3:::ap-southeast-2-greengrass-updates/*", "arn:aws:s3:::eu-central-1-greengrass-updates/*", "arn:aws:s3:::eu-west-1-greengrass-updates/*" ] } ] }
-
- Política de confiança
-
A política de confiança anexada à função deve permitir a ação
sts:AssumeRole
e definiriot.amazonaws.com
como um principal. Isso permite que o AWS IoT Core assuma a função como uma entidade confiável. Veja a seguir um exemplo de documento de política:{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowIotToAssumeRole", "Action": "sts:AssumeRole", "Principal": { "Service": "iot.amazonaws.com" }, "Effect": "Allow" } ] }
Além disso, o usuário que inicia uma atualização OTA deve ter permissões para usar greengrass:CreateSoftwareUpdateJob
e iot:CreateJob
e para usar iam:PassRole
para passar as permissões da função de assinante. Veja a seguir um exemplo de política do IAM:
{ "Version": "2012-10-17", "Statement": [ { "Action": [ "greengrass:CreateSoftwareUpdateJob" ], "Effect": "Allow", "Resource": "*" }, { "Effect": "Allow", "Action": [ "iot:CreateJob" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "iam:PassRole" ], "Resource": "
arn-of-s3-url-signer-role
" } ] }
Considerações
Antes de iniciar uma atualização OTA do software de núcleo do Greengrass, esteja ciente do impacto sobre os dispositivos no seu grupo do Greengrass, tanto no dispositivo de núcleo quanto nos dispositivos cliente conectados localmente a esse núcleo:
-
O núcleo é desligado durante a atualização.
-
Todas as funções Lambda em execução no núcleo serão desativadas. Se essas funções gravarem em recursos locais, elas poderão deixá-los em um estado incorreto, a menos que seja encerrado corretamente.
-
Durante o período de inatividade do núcleo, todas as suas conexões com a Nuvem AWS serão perdidas. As mensagens roteadas pelo núcleo por dispositivos cliente são perdidas.
-
Os caches da credencial são perdidos.
-
As filas que retêm trabalhos pendentes para funções Lambda são perdidas.
-
Funções do Lambda de longa duração perdem as informações de estado dinâmico e todos os trabalhos pendentes são descartados.
As seguintes informações de estado são preservadas durante a atualização OTA:
-
Arquivo de núcleo
-
Configuração de grupo do Greengrass
-
Sombras locais
-
Logs do Greengrass
-
Registros do atendente de atualizações OTA
Agente de atualizações OTA do Greengrass
O atendente de atualizações OTA do Greengrass é o componente de software do dispositivo que processa as tarefas de atualização criadas e implantadas na nuvem. O atendente de atualizações OTA é distribuído no mesmo pacote de software que o software de núcleo do AWS IoT Greengrass. O atendente está localizado em /
. Ele grava logs em greengrass-root
/ota/ota_agent/ggc-ota/var/log/greengrass/ota/ggc_ota.txt
.
nota
greengrass-root
representa o caminho no qual o software de núcleo do AWS IoT Greengrass é instalado no dispositivo. Normalmente, esse é o diretório /greengrass
.
É possível iniciar o atendente de atualizações OTA executando o binário manualmente ou integrando-o como parte de um script init, como um arquivo de serviço systemd. Se você executar o binário manualmente, ele deverá ser executado como root. Quando ele começa, o atendente de atualizações OTA para AWS IoT Greengrass escuta trabalhos de atualização de software do AWS IoT Core e os executa sequencialmente. O atendente de atualizações OTA do Greengrass ignora todos os outros tipos de trabalho AWS IoT.
O trecho a seguir mostra um exemplo de um arquivo de serviço systemd para iniciar, parar e reiniciar o atendente de atualizações OTA:
[Unit] Description=Greengrass OTA Daemon [Service] Type=forking Restart=on-failure ExecStart=/greengrass/ota/ota_agent/ggc-ota [Install] WantedBy=multi-user.target
Um núcleo que é o destino de uma atualização não deve executar duas instâncias do atendente de atualizações OTA. Isso faz com que os dois atendente s processem as mesmas tarefas, o que cria conflitos.
Integração com sistemas Init
Durante uma atualização OTA, o atendente de atualizações OTA reinicia os binários no dispositivo de núcleo. Se os binários estiverem em execução, isso poderá causar conflitos quando um sistema init estiver monitorando o estado do software de núcleo do AWS IoT Greengrass ou do atendente durante a atualização. Para ajudar a integrar o mecanismo de atualização OTA às suas estratégias de monitoramento, grave scripts de shell que são executados antes e depois de uma atualização. Por exemplo, você pode usar o script ggc_pre_update.sh
para fazer backup de dados ou interromper processos antes que o dispositivo seja desligado.
Para instruir o atendente de atualizações OTA a executar esses scripts, é necessário incluir o sinalizador "managedRespawn" : true
no arquivo config.json. Essa configuração é mostrada no seguinte trecho:
{ "coreThing": { … }, "runtime": { … }, "managedRespawn": true … }
Respawn gerenciado com atualizações OTA
Os requisitos a seguir se aplicam às atualizações do OTA com o managedRespawn
definido como true
:
-
Os seguintes scripts de shell devem estar presentes no diretório
/
:greengrass-root
/usr/scripts-
ggc_pre_update.sh
-
ggc_post_update.sh
-
ota_pre_update.sh
-
ota_post_update.sh
-
-
Os scripts devem retornar um código de retorno bem-sucedido.
-
Os scripts devem ser de propriedade de root e executáveis somente pelo root.
-
O script
ggc_pre_update.sh
deve interromper o daemon do Greengrass. -
O script
ggc_post_update.sh
deve iniciar o daemon do Greengrass.
nota
Como o atendente de atualizações OTA gerencia seu próprio processo, os ota_pre_update.sh
e scripts ota_post_update.sh
não precisam parar ou iniciar o serviço OTA.
O atendente de atualizações OTA executa os scripts a partir do /
. A árvore de diretórios deve ser semelhante a:greengrass-root
/usr/scripts
<greengrass_root> |-- certs |-- config | |-- config.json |-- ggc |-- usr/scripts | |-- ggc_pre_update.sh | |-- ggc_post_update.sh | |-- ota_pre_update.sh | |-- ota_post_update.sh |-- ota
Se managedRespawn
estiver definido como true
, o atendente de atualizações OTA verificará o diretório /
para localizar esses scripts antes e depois da atualização de software. Se os scripts não existirem, a atualização falhará. AWS IoT Greengrass não validará o conteúdo desses scripts. Como prática recomendada, verifique se seus scripts funcionam corretamente e emita códigos de saída apropriados para os erros.greengrass-root
/usr/scripts
Para atualizações OTA do software de núcleo do AWS IoT Greengrass:
-
Antes de iniciar a atualização, o atendente executa o script
ggc_pre_update.sh
. Use esse script para comandos que precisam ser executados antes que o atendente de atualizações OTA inicie a atualização do software AWS IoT Greengrass Core, como fazer backup de dados ou interromper qualquer processo em execução. O exemplo a seguir mostra um script simples para interromper o daemon do Greengrass.#!/bin/bash set -euo pipefail systemctl stop greengrass
-
Depois de concluir a atualização, o atendente executa o script
ggc_post_update.sh
. Use esse script para comandos que precisam ser executados depois que o atendente de atualizações OTA iniciar a atualização do software AWS IoT Greengrass Core, como para reiniciar processos. O exemplo a seguir mostra um script simples para iniciar o daemon do Greengrass.#!/bin/bash set -euo pipefail systemctl start greengrass
Para atualizações OTA do atendente de atualizações OTA:
-
Antes de iniciar a atualização, o atendente executa o script
ota_pre_update.sh
. Use esse script para comandos que precisam ser executados antes que o atendente de atualizações OTA se atualize, como fazer backup de dados ou interromper qualquer processo em execução. -
Depois de concluir a atualização, o atendente executa o script
ota_post_update.sh
. Use esse script para comandos que precisam ser executados após a atualização do atendente de atualizações OTA, como para reiniciar processos.
nota
Se managedRespawn
estiver definido como false
, o atendente de atualizações OTA não executará os scripts.
Criar uma atualização OTA
Siga estas etapas para executar uma atualização OTA do software do AWS IoT Greengrass em um ou mais núcleos:
-
Verifique se seus núcleos atendem aos requisitos para atualizações OTA.
nota
Se você configurou um sistema init para gerenciar o software AWS IoT Greengrass Core ou do atendente de atualizações OTA, verifique o seguinte em seus núcleos:
-
O arquivo config.json especifica
"managedRespawn" : true
. -
O diretório /
greengrass-root
/usr/scripts contém os seguintes scripts:-
ggc_pre_update.sh
-
ggc_post_update.sh
-
ota_pre_update.sh
-
ota_post_update.sh
-
Para obter mais informações, consulte Integração com sistemas Init.
-
-
Em um terminal de dispositivo núcleo, inicie o atendente de atualizações OTA.
cd /
greengrass-root
/ota/ota_agent sudo ./ggc-otanota
greengrass-root
representa o caminho no qual o software de núcleo do AWS IoT Greengrass é instalado no dispositivo. Normalmente, esse é o diretório/greengrass
.Não inicie várias instâncias do atendente de atualizações OTA em um núcleo porque isso pode causar conflitos.
-
Use a API do AWS IoT Greengrass para criar um trabalho de atualização de software.
-
Chame a API CreateSoftwareUpdateJob. Neste procedimento de exemplo, usamos comandos da AWS CLI.
O comando a seguir cria um trabalho que atualiza o software de núcleo do AWS IoT Greengrass em um núcleo. Substitua os valores de exemplo e execute o comando.
O comando retorna a seguinte resposta.
{ "IotJobId": "GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE", "IotJobArn": "arn:aws:iot:
region
:123456789012:job/GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE", "PlatformSoftwareVersion": "1.10.1" } -
Copie o
IoTJobId
da resposta. -
Chame DescribeJob na API do AWS IoT Core para ver o status do trabalho. Substitua o valor de exemplo pelo ID do trabalho e execute o comando.
aws iot describe-job --job-id GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE
O comando retorna um objeto de resposta que contém informações sobre o trabalho, incluindo
status
ejobProcessDetails
.{ "job": { "jobArn": "arn:aws:iot:
region
:123456789012:job/GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE", "jobId": "GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE", "targetSelection": "SNAPSHOT", "status": "IN_PROGRESS", "targets": [ "arn:aws:iot:region
:123456789012:thing/myCoreDevice" ], "description": "This job was created by Greengrass to update the Greengrass Cores in the targets with version 1.10.1 of the core software running on x86_64 architecture.", "presignedUrlConfig": { "roleArn": "arn:aws::iam::123456789012:role/myS3UrlSignerRole", "expiresInSec": 3600 }, "jobExecutionsRolloutConfig": {}, "createdAt": 1588718249.079, "lastUpdatedAt": 1588718253.419, "jobProcessDetails": { "numberOfCanceledThings": 0, "numberOfSucceededThings": 0, "numberOfFailedThings": 0, "numberOfRejectedThings": 0, "numberOfQueuedThings": 1, "numberOfInProgressThings": 0, "numberOfRemovedThings": 0, "numberOfTimedOutThings": 0 }, "timeoutConfig": {} } }
Para obter ajuda sobre a solução de problemas, consulte Solução de problemas de AWS IoT Greengrass.
-
API CreateSoftwareUpdateJob
Você pode usar a API CreateSoftwareUpdateJob
para atualizar o software AWS IoT Greengrass Core ou o software do atendente de atualizações OTA em seus dispositivos de núcleo. Essa API cria um trabalho de snapshot do AWS IoT que notifica os dispositivos quando uma atualização está disponível. Depois de chamar CreateSoftwareUpdateJob
, você pode usar outros comandos de trabalho do AWS IoT para controlar a atualização de software. Para obter mais informações, consulte Trabalhos no Guia do desenvolvedor do AWS IoT.
O exemplo a seguir mostra como usar a AWS CLI para criar um trabalho que atualiza o software de núcleo do AWS IoT Greengrass em um dispositivo de núcleo:
aws greengrass create-software-update-job \ --update-targets-architecture x86_64 \ --update-targets [\"arn:aws:iot:
region
:123456789012:thing/myCoreDevice\"] \ --update-targets-operating-system ubuntu \ --software-to-update core \ --s3-url-signer-role arn:aws:iam::123456789012:role/myS3UrlSignerRole \ --update-agent-log-level WARN \ --amzn-client-token myClientToken1
O comando create-software-update-job
retorna uma resposta JSON que contém o ID do trabalho, o ARN do trabalho e a versão do software que foi instalada pela atualização:
{
"IotJobId": "GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE",
"IotJobArn": "arn:aws:iot:region
:123456789012:job/GreengrassUpdateJob_c3bd7f36-ee80-4d42-8321-a1da0EXAMPLE",
"PlatformSoftwareVersion": "1.9.2"
}
Para obter as etapas que mostram como usar create-software-update-job
para atualizar um dispositivo de núcleo, consulte Criar uma atualização OTA.
O comando create-software-update-job
tem os seguintes parâmetros:
--update-targets-architecture
-
A arquitetura do dispositivo de núcleo.
Valores válidos:
armv7l
,armv6l
,x86_64
ouaarch64
--update-targets
-
Os núcleos a serem atualizados. A lista pode conter ARNs de núcleos individuais e ARNs de grupos de coisas cujos membros são núcleos. Para obter mais informações sobre grupos de coisas, consulte Grupos de coisas estáticas no Guia do usuário do AWS IoT.
--update-targets-operating-system
-
O sistema operacional do dispositivo de núcleo.
Valores válidos:
ubuntu
,amazon_linux
,raspbian
ouopenwrt
--software-to-update
-
Especifica se o software do núcleo ou o software do atendente de atualizações OTA devem ser atualizados.
Valores válidos:
core
ouota_agent
--s3-url-signer-role
-
O ARN do perfil do IAM usado para pré-assinar o URL do Amazon S3 que vincula aos artefatos de atualização de software do AWS IoT Greengrass. A política de permissões anexadas da função deve permitir a ação
s3:GetObject
nos buckets nas regiões de destino das Região da AWSs. A função também deve permitir queiot.amazonaws.com
assuma a função como uma entidade confiável. Para obter mais informações, consulte Permissões do IAM para atualizações OTA. --amzn-client-token
-
(Opcional) Um token do cliente usado para fazer solicitações idempotentes. Forneça um token exclusivo para impedir que atualizações duplicadas sejam criadas por causa de novas tentativas internas.
--update-agent-log-level
-
(Opcional) O nível de registro em log para instruções de log geradas pelo atendente de atualizações OTA. O padrão é
ERROR
.Valores válidos:
NONE
,TRACE
,DEBUG
,VERBOSE
,INFO
,WARN
,ERROR
ouFATAL
nota
CreateSoftwareUpdateJob
aceita solicitações somente para as seguintes combinações de arquitetura e sistema operacional compatíveis:
-
ubuntu/x86_64
-
ubuntu/aarch64
-
amazon_linux/x86_64
-
raspbian/armv7l
-
raspbian/armv6l
-
openwrt/aarch64
-
openwrt/armv7l