Procedimento de imagem dourada

As seções a seguir descrevem o procedimento para criar uma imagem dourada e gravá-la em cada dispositivo na linha de produção.

Crie seu dispositivo dourado

Etapa 1: instalar e provisionar o Greengrass.

Instale o tempo de execução do Greengrass edge em seu dispositivo dourado, como você normalmente faria, e provisione-o usando seu método de provisionamento preferido.

Etapa 2: implante seus componentes.

Da nuvem, implante os componentes e a configuração do seu aplicativo em seu dispositivo dourado, como você normalmente faria.

Leia a imagem dourada do seu dispositivo dourado

Agora você pode fotografar seu dispositivo dourado para criar uma imagem dourada.

Etapa 1: Encerrar o Greengrass.

Encerre o serviço Greengrass em seu dispositivo dourado. Por exemplo:

sudo systemctl stop greengrass.service

Etapa 2: Crie um instantâneo da árvore de arquivos do Greengrass.

Dependendo do seu método dourado preferido, tire um instantâneo completo ou parcial da árvore de arquivos do Greengrass e inclua-o em sua imagem dourada.

Etapa 3: copie suas imagens do Docker.

Se seus componentes usam imagens do Docker como artefatos, tire um instantâneo do registro de imagens do Docker e inclua-o na sua imagem dourada.

Como alternativa, você pode usar docker save para criar um arquivo de cada imagem do Docker e copiá-las do dispositivo dourado. Por exemplo:

user@machine:~/environment $ docker images
REPOSITORY                     TAG       IMAGE ID       CREATED      SIZE
homeassistant/home-assistant   2024.6    2b4c9de733f1   9 days ago   1.6GB
user@machine:~/environment $ docker save homeassistant/home-assistant | gzip > home-assistant.tar.gz

Em geral, essa abordagem é mais lenta do que adicionar o registro de imagens do Docker à sua imagem dourada.

Escreva a imagem dourada em seus dispositivos de produção

Agora você precisa escrever a imagem dourada em cada um dos dispositivos de produção que passam pela linha de fabricação. As etapas a seguir normalmente seriam automatizadas usando scripts.

Etapa 1: escreva a imagem.

Grave sua imagem dourada no dispositivo de produção. Certifique-se de que ele inclua o instantâneo completo ou parcial da árvore de diretórios do Greengrass e do registro de imagens do Docker, conforme aplicável.

Etapa 2: Carregar imagens do Docker.

Se você optou por usar docker save para copiar artefatos de imagem do Docker do seu dispositivo dourado, use docker load para carregar essas imagens no seu dispositivo de produção. Por exemplo:

user@machine:~/environment $ docker load < home-assistant.tar.gz
user@machine:~/environment $ docker images
REPOSITORY                     TAG       IMAGE ID       CREATED      SIZE
homeassistant/home-assistant   2024.6    2b4c9de733f1   9 days ago   1.6GB

Em geral, essa abordagem é mais lenta do que adicionar o registro de imagens do Docker à sua imagem dourada.

Etapa 3: adicione credenciais.

Se seu dispositivo não usa o provisionamento de frota, instale o certificado X.509 exclusivo e a chave privada para o dispositivo de produção, substituindo as credenciais douradas do dispositivo. O método exato de fazer isso depende se você usa um módulo de segurança de hardware (HSM) e sua infraestrutura de chave pública (PKI) específica.

Configure seus dispositivos de produção

Depois de escrever a imagem dourada, você deve configurar cada dispositivo de produção. Essa configuração depende se você usa o método de snapshot completo ou parcial do Greengrass. As etapas devem ser automatizadas.

Método completo de captura instantânea do Greengrass

Importante

Siga essas etapas somente se você estiver usando o método completo de snapshot do Greengrass.

Etapa 1: Edite a configuração.

Edite o arquivo config/effectiveConfig.yaml. Por exemplo:

sudo nano /greengrass/v2/config/effectiveConfig.yaml

Etapa 2: defina o nome da coisa.

As ações necessárias para definir o nome do novo dispositivo de produção dependem de você estar usando o provisionamento de frota. Faça as modificações corretas para seu caso de uso.

Se você não estiver usando o provisionamento de frota, poderá definir o nome do item do seu dispositivo de produção editando a thingName propriedade para substituir o nome dourado do dispositivo pelo nome do item do dispositivo de produção. Por exemplo:

system:
  certificateFilePath: "/greengrass/v2/thingCert.crt"
  privateKeyPath: "/greengrass/v2/privKey.key"
  rootCaPath: "/greengrass/v2/rootCA.pem"
  rootpath: "/greengrass/v2"
  thingName: "ProductionDeviceThingName1"

Se você estiver usando o provisionamento de frota, primeiro deverá apagar parte da configuração dourada do dispositivo para garantir que o plug-in de provisionamento de frota seja executado no dispositivo de produção. Você pode fazer isso substituindo o nome dourado do dispositivo na thingName propriedade por uma string vazia. Por exemplo:

system:
  certificateFilePath: "/greengrass/v2/thingCert.crt"
  privateKeyPath: "/greengrass/v2/privKey.key"
  rootCaPath: "/greengrass/v2/rootCA.pem"
  rootpath: "/greengrass/v2"
  thingName: ""

Além disso, você deve adicionar a configuração do plug-in de aprovisionamento de frota à services propriedade e passar o nome do dispositivo de produção como uma propriedade dentro da templateParameters propriedade. O exemplo a seguir pressupõe que o modelo de aprovisionamento de frota tenha um parâmetro chamado eThingName, portanto, haja uma ThingName propriedade dentro da configuração templateParameters do plug-in:

system:
  certificateFilePath: "/greengrass/v2/thingCert.crt"
  privateKeyPath: "/greengrass/v2/privKey.key"
  rootCaPath: "/greengrass/v2/rootCA.pem"
  rootpath: "/greengrass/v2"
  thingName: ""
services:
  aws.greengrass.FleetProvisioningByClaim:
    configuration:
      rootPath: "/greengrass/v2"
      awsRegion: "us-east-1"
      iotDataEndpoint: "<prefix>-ats.iot.us-east-1.amazonaws.com"
      iotCredentialEndpoint: "<prefix>.credentials.iot.us-east-1.amazonaws.com"
      iotRoleAlias: "GreengrassCoreTokenExchangeRoleAlias"
      provisioningTemplate: "GreengrassFleetProvisioningTemplate"
      claimCertificatePath: "/greengrass/v2/claim-certs/claim.pem.crt"
      claimCertificatePrivateKeyPath: "/greengrass/v2/claim-certs/claim.private.pem.key"
      rootCaPath: "/greengrass/v2/rootCA.pem"
      templateParameters:
        ThingName: "ProductionDeviceThingName1"

Seu caso de uso pode exigir alguns parâmetros de configuração do plug-in de provisionamento de frota diferentes dos mostrados aqui. Para obter mais informações, consulte Configurar o plug-in de provisionamento de AWS IoT frota na AWS IoT Greengrass documentação.

Etapa 3: atualize os nomes das coisas interpoladas.

Se você tiver algum componente que use a variável de iot:thingName receita para interpolar o nome da coisa, provavelmente terá instruções de controle de acesso nas quais o nome dourado da coisa do dispositivo foi interpolado. Por exemplo, no caso do componente comunitário Certificate Rotator:

services:
  aws.greengrass.labs.CertificateRotator:
    componentType: "GENERIC"
    configuration:
      accessControl:
        aws.greengrass.ipc.mqttproxy:
          aws.greengrass.labs.CertificateRotator:mqttproxy:1:
            operations:
            - "aws.greengrass#PublishToIoTCore"
            policyDescription: "Allows access to publish to relevant topics"
            resources:
            - "$aws/things/GoldenDeviceThingName/jobs/+/get"
            - "$aws/things/GoldenDeviceThingName/jobs/+/update"
            - "awslabs/things/GoldenDeviceThingName/certificate/create"
            - "awslabs/things/GoldenDeviceThingName/certificate/commit"
          aws.greengrass.labs.CertificateRotator:mqttproxy:2:
            operations:
            - "aws.greengrass#SubscribeToIoTCore"
            policyDescription: "Allows access to subscribe to relevant topics"
            resources:
            - "$aws/things/GoldenDeviceThingName/jobs/notify-next"
            - "$aws/things/GoldenDeviceThingName/jobs/+/get/accepted"
            - "$aws/things/GoldenDeviceThingName/jobs/+/get/rejected"
            - "$aws/things/GoldenDeviceThingName/jobs/+/update/accepted"
            - "$aws/things/GoldenDeviceThingName/jobs/+/update/rejected"
            - "awslabs/things/GoldenDeviceThingName/certificate/create/accepted"
            - "awslabs/things/GoldenDeviceThingName/certificate/create/rejected"
            - "awslabs/things/GoldenDeviceThingName/certificate/commit/accepted"
            - "awslabs/things/GoldenDeviceThingName/certificate/commit/rejected"
      keyAlgorithm: "RSA-2048"
      signingAlgorithm: "SHA256WITHRSA"

Em todos esses casos, você deve substituir todas as instâncias do nome dourado do dispositivo pelo nome do item do dispositivo de produção.

Etapa 4: remova os segredos dourados do dispositivo.

Examine se effectiveConfig.yaml há segredos criptografados que foram armazenados pelo seu dispositivo dourado. Eles serão armazenados na configuração do componente do gerenciador secreto. Por exemplo:

  aws.greengrass.SecretManager:
    componentType: "PLUGIN"
    configuration:
      cloudSecrets:
      - arn: "arn:aws:secretsmanager:us-east-1:111122223333:secret:greengrass-home-assistant-KIzJfZ"
    dependencies:
    - "aws.greengrass.Nucleus:SOFT"
    lifecycle: {}
    runtime:
      secretResponse: "{\"secrets\":[{\"arn\":\"arn:aws:secretsmanager:us-east-1:111122223333:secret:greengrass-home-assistant-KIzJfZ\"\
        ,\"name\":\"greengrass-home-assistant\",\"versionId\":\"8e481177-9250-4458-9f1f-3690d28e4ae9\"\
        ,\"encryptedSecretString\":\"AgV4Rpc9 ... MYeVALYQ==\"\
        ,\"versionStages\":[\"AWSCURRENT\"],\"createdDate\":1660648425915}]}"
    version: "2.1.8"

Você deve excluir esse segredo para garantir que seu dispositivo de produção não tente descriptografar um segredo que foi criptografado pelo dispositivo dourado. Exclua a secretResponse propriedade. Por exemplo:

  aws.greengrass.SecretManager:
    componentType: "PLUGIN"
    configuration:
      cloudSecrets:
      - arn: "arn:aws:secretsmanager:us-east-1:111122223333:secret:greengrass-home-assistant-KIzJfZ"
    dependencies:
    - "aws.greengrass.Nucleus:SOFT"
    lifecycle: {}
    runtime:
    version: "2.1.8"

Etapa 5: aplique a configuração alterada.

Aplique a configuração alterada para atualizarconfig/config.tlog. Por exemplo:

sudo java -Droot="/greengrass/v2" \
  -jar /greengrass/v2/alts/current/distro/lib/Greengrass.jar \
  --start false \
  --init-config /greengrass/v2/config/effectiveConfig.yaml

Método de captura instantânea parcial do Greengrass

A configuração de seus dispositivos de produção é trivial se você usar o método de captura instantânea parcial do Greengrass. O procedimento é idêntico ao procedimento normal de configuração parcial do bootstrap quando você instala o Greengrass, exceto que a configuração inicial é passada para o runtime do Greengrass que já está instalado.

Importante

Siga essas etapas somente se você estiver usando o método de snapshot parcial do Greengrass.

Etapa 1: Crie a configuração.

A configuração parcial necessária depende se você está usando o provisionamento de frota. Certifique-se de fazer as modificações corretas para seu caso de uso.

Se você não estiver usando o provisionamento de frota, poderá criar um arquivo de configuração parcial que não inclua nenhuma configuração para o plug-in de provisionamento de frota. Defina a thingName propriedade como o nome do item do seu dispositivo de produção. Por exemplo:

system:
  certificateFilePath: "/greengrass/v2/device.pem.crt"
  privateKeyPath: "/greengrass/v2/private.pem.key"
  rootCaPath: "/greengrass/v2/AmazonRootCA1.pem"
  rootpath: "/greengrass/v2"
  thingName: "ProductionDeviceThingName1"
services:
  aws.greengrass.Nucleus:
    componentType: "NUCLEUS"
    version: "2.12.6"
    configuration:
      awsRegion: "us-east-1"
      iotRoleAlias: "GreengrassCoreTokenExchangeRoleAlias"
      iotDataEndpoint: "<prefix>-ats.iot.us-east-1.amazonaws.com"
      iotCredEndpoint: "<prefix>.credentials.iot.us-east-1.amazonaws.com"

Se você estiver usando o provisionamento de frota, a configuração parcial deve incluir a configuração do plug-in de provisionamento de frota. Essa configuração deve passar o nome do dispositivo de produção como uma propriedade dentro da templateParameters propriedade. O exemplo a seguir pressupõe que o modelo de aprovisionamento de frota tenha um parâmetro chamado eThingName, portanto, haja uma ThingName propriedade dentro da configuração templateParameters do plug-in:

services:
  aws.greengrass.Nucleus:
    version: "2.12.6"
  aws.greengrass.FleetProvisioningByClaim:
    configuration:
      rootPath: "/greengrass/v2"
      awsRegion: "us-east-1"
      iotDataEndpoint: "<prefix>-ats.iot.us-east-1.amazonaws.com"
      iotCredentialEndpoint: "<prefix>.credentials.iot.us-east-1.amazonaws.com"
      iotRoleAlias: "GreengrassCoreTokenExchangeRoleAlias"
      provisioningTemplate: "GreengrassFleetProvisioningTemplate"
      claimCertificatePath: "/greengrass/v2/claim-certs/claim.pem.crt"
      claimCertificatePrivateKeyPath: "/greengrass/v2/claim-certs/claim.private.pem.key"
      rootCaPath: "/greengrass/v2/AmazonRootCA1.pem"
      templateParameters:
        ThingName: "ProductionDeviceThingName1"

Seu caso de uso pode exigir parâmetros de configuração do plug-in de provisionamento de frota diferentes dos mostrados aqui. Para obter mais informações, consulte Configurar o plug-in de provisionamento de AWS IoT frota na AWS IoT Greengrass documentação.

Etapa 2: aplique a configuração.

Aplique a configuração para criarconfig/config.tlog. Por exemplo:

sudo java -Droot="/greengrass/v2" \
  -jar /greengrass/v2/alts/current/distro/lib/Greengrass.jar \
  --start false \
  --init-config config.yaml