Execute AWS IoT Greengrass em um contêiner Docker com provisionamento automático de recursos - AWS IoT Greengrass
Pré-requisitosConfigurar as credenciais da AWSCriar um arquivo de ambienteExecute o software AWS IoT Greengrass CorePróximas etapas

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

Execute AWS IoT Greengrass em um contêiner Docker com provisionamento automático de recursos

Este tutorial mostra como instalar e executar o software AWS IoT Greengrass Core em um contêiner Docker com AWS recursos provisionados automaticamente e ferramentas de desenvolvimento local. Você pode usar esse ambiente de desenvolvimento para explorar os AWS IoT Greengrass recursos em um contêiner do Docker. O software requer credenciais da AWS para provisionar esses recursos e implantar as ferramentas de desenvolvimento local.

Se você não puder fornecer AWS credenciais para o contêiner, poderá provisionar os AWS recursos que o dispositivo principal precisa para operar. Também é possível implantar as ferramentas de desenvolvimento em um dispositivo principal para usar como dispositivo de desenvolvimento. Isso permite que você forneça menos permissões ao dispositivo ao executar o contêiner. Para obter mais informações, consulte Execute AWS IoT Greengrass em um contêiner Docker com provisionamento manual de recursos.

Pré-requisitos

Para concluir este tutorial, você precisará do seguinte:

  • Um Conta da AWS. Se você não tiver uma, consulte Configurar um Conta da AWS.

  • Um usuário AWS do IAM com permissões para provisionar os recursos do IAM AWS IoT e do IAM para um dispositivo principal do Greengrass. O instalador do software AWS IoT Greengrass Core usa suas AWS credenciais para provisionar automaticamente esses recursos. Para obter informações sobre a política mínima do IAM para provisionar recursos automaticamente, consulte Política mínima de IAM para o instalador provisionar recursos.

  • Uma imagem AWS IoT Greengrass do Docker. Você pode criar uma imagem a partir do AWS IoT Greengrass Dockerfile.

  • O computador host em que você executa o contêiner do Docker deve atender aos seguintes requisitos:

    • Sistema operacional baseado em Linux com conexão à Internet.

    • Docker Engine, versão 18.09 ou posterior.

    • (Opcional) Docker Compose versão 1.22 ou posterior. O Docker Compose é necessário somente se você quiser usar a CLI do Docker Compose para executar suas imagens do Docker.

Configurar as credenciais da AWS

Nesta etapa, você cria um arquivo de credencial no computador host que contém suas credenciais de segurança da AWS . Ao executar a imagem do AWS IoT Greengrass Docker, você deve montar a pasta que contém esse arquivo de credencial /root/.aws/ no contêiner do Docker. O AWS IoT Greengrass instalador usa essas credenciais para provisionar recursos no seu Conta da AWS. Para obter informações sobre a política mínima do IAM que o instalador exige para provisionar recursos automaticamente, consulte Política mínima de IAM para o instalador provisionar recursos.

  1. Recupere um dos seguintes.

  2. Crie uma pasta onde você coloca seu arquivo de credencial.

    mkdir ./greengrass-v2-credentials

  3. Utilize um editor de texto para criar um arquivo de configuração com o nome credentials na pasta ./greengrass-v2-credentials.

    Por exemplo, você pode executar o seguinte comando para usar o GNU nano para criar o arquivo credentials. 

    nano ./greengrass-v2-credentials/credentials

  4. Adicione suas AWS credenciais ao credentials arquivo no formato a seguir.

    [default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token = AQoEXAMPLEH4aoAH0gNCAPy...truncated...zrkuWJOgQs8IZZaIv2BXIa2R4Olgk

    Inclua aws_session_token somente para credenciais temporárias.

Importante

Remova o arquivo de credencial do computador host depois de iniciar o AWS IoT Greengrass contêiner. Se você não remover o arquivo de credenciais, suas AWS credenciais permanecerão montadas dentro do contêiner. Para obter mais informações, consulte Execute o software AWS IoT Greengrass principal em um contêiner.

Criar um arquivo de ambiente

Este tutorial usa um arquivo de ambiente para definir as variáveis de ambiente que serão passadas para o instalador do software AWS IoT Greengrass Core dentro do contêiner Docker. Você também pode usar o argumento -e ou --env em seu comando docker run para definir variáveis de ambiente no contêiner do Docker ou definir as variáveis em um bloco environment no arquivo docker-compose.yml.

  1. Use um editor de texto para criar um arquivo de ambiente chamado .env.

    Por exemplo, em um sistema baseado em Linux, você pode executar o comando a seguir para usar o GNU nano para criar o .env no diretório atual.

    nano .env

  2. Copie o conteúdo a seguir para o arquivo.

    GGC_ROOT_PATH=/greengrass/v2
AWS_REGION=region
PROVISION=true
THING_NAME=MyGreengrassCore
THING_GROUP_NAME=MyGreengrassCoreGroup
TES_ROLE_NAME=GreengrassV2TokenExchangeRole
TES_ROLE_ALIAS_NAME=GreengrassCoreTokenExchangeRoleAlias
COMPONENT_DEFAULT_USER=ggc_user:ggc_group

    Em seguida, substitua os valores a seguir:

    • /greengrass/v2. A pasta raiz do Greengrass que você deseja usar para instalação. Use a variável de ambiente GGC_ROOT para definir esse valor.

    • region. O Região da AWS local em que você criou os recursos.

    • MyGreengrassCore. O nome da AWS IoT coisa. Se o objeto não existir, o instalador o cria. O instalador baixa os certificados para autenticar a AWS IoT coisa.

    • MyGreengrassCoreGroup. O nome do grupo de AWS IoT coisas. Se o grupo de objetos não existir, o instalador o cria e adiciona o objeto a ele. Se o grupo de objetos existir e tiver uma implantação ativa, o dispositivo principal baixará e executará o software especificado pela implantação.

    • GreengrassV2TokenExchangeRole. Substitua pelo nome da função de troca de tokens do IAM que permite que o dispositivo principal do Greengrass obtenha credenciais temporárias AWS . Se a função não existir, o instalador a cria, cria e anexa uma política chamada GreengrassV2TokenExchangeRole Access. Para obter mais informações, consulte Autorize os dispositivos principais a interagir com os serviços da AWS.

    • GreengrassCoreTokenExchangeRoleAlias. O alias da função de troca de tokens. Se o alias da função não existir, o instalador o cria e o direciona para a função de troca de tokens do IAM que você especifica. Para obter mais informações, consulte .

    nota

    Você pode definir a variável de ambiente DEPLOY_DEV_TOOLS para true a fim de implantar o componente CLI do Greengrass, que permite desenvolver componentes personalizados dentro do contêiner do Docker. Recomendamos que você use este componente somente em ambientes de desenvolvimento, não em ambientes de produção. Este componente fornece acesso a informações e operações que você normalmente não precisará em um ambiente de produção. Siga o princípio do privilégio mínimo implantando este componente somente nos dispositivos principais em que você precisar dele.

Execute o software AWS IoT Greengrass principal em um contêiner

Este tutorial mostra como iniciar a imagem do Docker que você criou em um contêiner do Docker. Você pode usar a CLI do Docker ou a CLI do Docker Compose para AWS IoT Greengrass executar a imagem do software Core em um contêiner do Docker.

Docker

  1. Execute o comando a seguir para iniciar o contêiner do Docker. 

    docker run --rm --init -it --name docker-image \
 -v path/to/greengrass-v2-credentials:/root/.aws/:ro \
 --env-file .env \
 -p 8883 \
 your-container-image:version

    Esse exemplo de comando usa os seguintes argumentos para docker run:

    • --rm. Limpa o contêiner quando ele sair.

    • --init. Usa um processo de inicialização no contêiner.

      nota

      O --init argumento é necessário para desligar o software AWS IoT Greengrass Core quando você interrompe o contêiner Docker.

    • -it. (Opcional) Executa o contêiner do Docker em primeiro plano como um processo interativo. Em vez disso, você pode substituir isso pelo argumento -d para executar o contêiner do Docker no modo desanexado. Para obter mais informações, consulte Detached vs foreground na documentação do Docker.

    • --name. Executa um contêiner chamado aws-iot-greengrass

    • -v. Monta um volume no contêiner do Docker para disponibilizar o arquivo de configuração e os arquivos de certificado para AWS IoT Greengrass execução dentro do contêiner.

    • --env-file. (Opcional) Especifica o arquivo de ambiente para definir as variáveis de ambiente que serão passadas para o instalador do software AWS IoT Greengrass Core dentro do contêiner Docker. Esse argumento é necessário somente se você criou um arquivo de ambiente para definir variáveis de ambiente. Se você não criou um arquivo de ambiente, pode usar argumentos --env para definir variáveis de ambiente diretamente no comando de execução do Docker.

    • -p. (Opcional) Publica a porta 8883 do contêiner na máquina host. Esse argumento é necessário se você quiser se conectar e se comunicar pelo MQTT porque o AWS IoT Greengrass usa a porta 8883 para tráfego MQTT. Para abrir outras portas, use argumentos -p adicionais.

    nota

    Para executar seu contêiner do Docker com maior segurança, você pode usar os argumentos --cap-drop e --cap-add para habilitar seletivamente os recursos do Linux para seu contêiner. Para obter mais informações, consulte Runtime privilege and Linux capabilities no site de documentação do Docker.

  2. Remova as credenciais ./greengrass-v2-credentials do dispositivo host.

    rm -rf ./greengrass-v2-credentials
    Importante

    Você está removendo essas credenciais porque elas fornecem amplas permissões que o dispositivo principal precisa somente durante a configuração. Se você não remover essas credenciais, os componentes do Greengrass e outros processos em execução no contêiner poderão acessá-las. Se você precisar fornecer AWS credenciais para um componente do Greengrass, use o serviço de troca de tokens. Para obter mais informações, consulte Interaja com AWS os serviços.

Docker Compose

  1. Use um editor de texto para criar um arquivo Compose do Docker chamado docker-compose.yml.

    Por exemplo, em um sistema baseado em Linux, você pode executar o comando a seguir para usar o GNU nano para criar o docker-compose.yml no diretório atual.

    nano docker-compose.yml
    nota

    Você também pode baixar e usar a versão mais recente do arquivo Compose AWS fornecido em. GitHub

  2. Adicione o conteúdo a seguir ao arquivo do Compose. O arquivo deve ser semelhante ao exemplo a seguir. docker-imageSubstitua pelo nome da sua imagem do Docker. 

    version: '3.7'
 
services:
  greengrass:
    init: true
    container_name: aws-iot-greengrass
    image: docker-image
    volumes:
      - ./greengrass-v2-credentials:/root/.aws/:ro 
    env_file: .env
    ports:
      - "8883:8883"

    Neste exemplo, os seguintes parâmetros no arquivo do Compose são opcionais:

    • ports: publica a porta 8883 do contêiner na máquina host. Esse parâmetro é necessário se você quiser se conectar e se comunicar pelo MQTT porque AWS IoT Greengrass usa a porta 8883 para tráfego MQTT.

    • env_file—Especifica o arquivo de ambiente para definir as variáveis de ambiente que serão passadas para o instalador do software AWS IoT Greengrass Core dentro do contêiner Docker. Esse parâmetro é necessário somente se você criou um arquivo de ambiente para definir variáveis de ambiente. Se você não criou um arquivo de ambiente, pode usar o parâmetro environment para definir variáveis de ambiente diretamente em seu arquivo Compose.

    nota

    Para executar seu contêiner do Docker com maior segurança, você pode usar os argumentos cap_drop e cap_add em seu arquivo do Compose para habilitar seletivamente os recursos do Linux para seu contêiner. Para obter mais informações, consulte Runtime privilege and Linux capabilities no site de documentação do Docker.

  3. Execute o comando a seguir para iniciar o contêiner do Docker.

    docker-compose -f docker-compose.yml up

  4. Remova as credenciais ./greengrass-v2-credentials do dispositivo host.

    rm -rf ./greengrass-v2-credentials
    Importante

    Você está removendo essas credenciais porque elas fornecem amplas permissões que o dispositivo principal precisa somente durante a configuração. Se você não remover essas credenciais, os componentes do Greengrass e outros processos em execução no contêiner poderão acessá-las. Se você precisar fornecer AWS credenciais para um componente do Greengrass, use o serviço de troca de tokens. Para obter mais informações, consulte Interaja com AWS os serviços.

Próximas etapas

AWS IoT Greengrass O software principal agora está sendo executado em um contêiner Docker. Execute o comando a seguir para recuperar o ID do contêiner em execução no momento.

docker ps

Em seguida, você pode executar o comando a seguir para acessar o contêiner e explorar o software AWS IoT Greengrass principal executado dentro do contêiner.

docker exec -it container-id /bin/bash

Para obter mais informações sobre a criação de um componente simples, consulte Etapa 4: desenvolver e testar um componente no dispositivo em Tutorial: Começando com AWS IoT Greengrass V2.

nota

Quando você usa docker exec para executar comandos dentro do contêiner do Docker, esses comandos não são registrados nos logs do Docker. Para registrar os comandos nos logs do Docker, anexe um shell interativo ao contêiner do Docker. Para obter mais informações, consulte Anexar um shell interativo ao contêiner do Docker.

O arquivo de log AWS IoT Greengrass principal é chamado greengrass.log e está localizado em/greengrass/v2/logs. Os arquivos de log do componente também estão localizados no mesmo diretório. Para copiar logs do Greengrass para um diretório temporário no host, execute o seguinte comando:

docker cp container-id:/greengrass/v2/logs /tmp/logs

Se você quiser manter os logs após a saída ou remoção de um contêiner, recomendamos que você vincule e monte somente o diretório /greengrass/v2/logs no diretório de logs temporários no host, em vez de montar todo o diretório Greengrass. Para obter mais informações, consulte Manter os logs do Greengrass fora do contêiner do Docker.

Para interromper a execução de um contêiner AWS IoT Greengrass Docker, execute docker stop oudocker-compose -f docker-compose.yml stop. Essa ação envia SIGTERM para o processo do Greengrass e encerra todos os processos associados que foram iniciados no contêiner. O contêiner do Docker é inicializado com o docker-init executável como processo PID 1, o que ajuda a eliminar quaisquer processos zumbis restantes. Para obter mais informações, consulte Specify an init process na documentação do Docker.

Para obter informações sobre como solucionar problemas com a execução do AWS IoT Greengrass em um contêiner do Docker, consulte Solução de problemas AWS IoT Greengrass em um contêiner Docker.