Arquivo de configuração da CLI do kit de desenvolvimento do Greengrass - AWS IoT Greengrass
Formato do arquivo de configuração da CLI do GDKExemplos de arquivos de configuração da CLI do GDK

Arquivo de configuração da CLI do kit de desenvolvimento do Greengrass

A interface de linha de comando do kit de desenvolvimento do AWS IoT Greengrass(CLI do GDK) lê um arquivo de configuração chamado gdk-config.json para criar e publicar componentes. Esse arquivo de configuração precisa estar na raiz do repositório de componentes. Você pode usar o comando init da CLI do GDK para inicializar repositórios de componentes com esse arquivo de configuração.

Formato do arquivo de configuração da CLI do GDK

Ao definir um arquivo de configuração da CLI do GDK para um componente, você especifica as seguintes informações no formato JSON.

gdk_version

A versão mínima da CLI do GDK compatível com esse componente. Esse valor deve ser uma das versões da CLI do GDK dos lançamentos.

component

A configuração desse componente.

componentName
author

O autor ou publicador do componente.

version

A versão do componente. Especifique um dos seguintes:

  • NEXT_PATCH: quando você escolhe essa opção, a CLI do GDK define a versão quando você publica o componente. A CLI do GDK consulta o serviço do AWS IoT Greengrass para identificar a versão mais recente publicada do componente. Em seguida, ela define a versão para a próxima versão de patch após essa versão. Se você não publicou o componente antes, a CLI do GDK usa a versão 1.0.0.

    Se você escolher essa opção, não poderá usar a CLI do Greengrass para implantar e testar localmente o componente em seu computador de desenvolvimento local que executa o software AWS IoT Greengrass Core. Para habilitar implantações locais, você deve especificar uma versão semântica em vez disso.

  • Uma versão semântica, como 1.0.0. As versões semânticas usam um sistema de numeração principal.secundário.patch. Para mais informações, consulte a especificação de versão semântica.

    Se você desenvolver componentes em um dispositivo principal do Greengrass para implantar e testar o componente, escolha essa opção. Você deve criar o componente com uma versão específica para criar implantações locais com a CLI do Greengrass.

build

A configuração a ser usada para criar a fonte desse componente em artefatos. Esse objeto contém as seguintes informações:

build_system

O sistema de compilação a ser usado. Escolha uma das seguintes opções:

  • zip: empacota a pasta do componente em um arquivo ZIP para definir como o único artefato do componente. Escolha essa opção para os seguintes tipos de componentes:

    • Componentes que usam linguagens de programação interpretadas, como Python ou JavaScript.

    • Componentes que empacotam arquivos que não sejam código, como modelos de machine learning ou outros recursos.

    A CLI do GDK compacta a pasta do componente em um arquivo zip com o mesmo nome da pasta do componente. Por exemplo, se o nome da pasta do componente for HelloWorld, a CLI do GDK cria um arquivo zip chamado HelloWorld.zip.

    nota

    Se você usa a CLI do GDK versão 1.0.0 em um dispositivo Windows, a pasta do componente e os nomes dos arquivos zip devem conter somente letras minúsculas.

    Quando a CLI do GDK compacta a pasta do componente em um arquivo zip, ela ignora os seguintes arquivos:

    • O arquivo gdk-config.json

    • O arquivo da fórmula (recipe.json ou recipe.yaml)

    • Crie pastas, como greengrass-build

  • maven: executa o comando mvn clean package para transformar a fonte do componente em artefatos. Escolha essa opção para componentes que usam o Maven, como componentes Java.

    Em dispositivos Windows, esse atributo está disponível para a CLI do GDK v1.1.0 e versões posteriores.

  • gradle: executa o comando gradle build para transformar a fonte do componente em artefatos. Escolha essa opção para componentes que usam o Gradle. Este atributo está disponível para a CLI do GDK v1.1.0 e posteriores.

    O sistema de compilação do gradle é compatível com o Kotlin DSL como arquivo de compilação. Este atributo está disponível para a CLI do GDK v1.2.0 e posteriores.

  • gradlew: executa o comando gradlew para transformar a fonte do componente em artefatos. Escolha essa opção para componentes que usam o Wrapper Gradle.

    Este atributo está disponível para a CLI do GDK v1.2.0 e posteriores.

  • custom: executa um comando personalizado para transformar a fonte do componente em uma fórmula e artefatos. Especifique o comando personalizado no parâmetro custom_build_command.

custom_build_command

(Opcional) O comando de compilação personalizado a ser executado em um sistema de compilação personalizado. Você deve especificar este parâmetro se especificar custom para build_system.

Importante

Esse comando deve criar uma fórmula e artefatos nas seguintes pastas dentro da pasta do componente. A CLI do GDK cria essas pastas para você quando você executa o comando de compilação do componente.

  • Pasta de fórmula: greengrass-build/recipes

  • Pasta de artefatos: greengrass-build/artifacts/componentName/componentVersion

    Substitua componentName pelo nome do componente e substitua componentVersion pela versão do componente ou NEXT_PATCH.

Você pode especificar uma única string ou uma lista de strings, em que cada string é uma palavra no comando. Por exemplo, para executar um comando de compilação personalizado para um componente C++, especifique cmake --build build --config Release ou ["cmake", "--build", "build", "--config", "Release"].

Para ver um exemplo de um sistema de compilação personalizado, consulte aws.greengrass.labs.LocalWebServer community component no GitHub.

options

(Opcional) Opções de configuração adicionais usadas durante o processo de compilação do componente.

Este atributo está disponível para a CLI do GDK v1.2.0 e posteriores.

excludes

Uma lista de padrões globais que definem quais arquivos excluir do diretório de componentes ao criar o arquivo zip. Válido somente quando a build_system é zip.

nota

Nas versões 1.4.0 e anteriores da CLI do GDK, qualquer arquivo que corresponda a uma entrada na lista de exclusões é excluído de todos os subdiretórios do componente. Para ter o mesmo comportamento nas versões 1.5.0 e posteriores da CLI do GDK, acrescente as entradas **/ existentes na lista de exclusões. Por exemplo, *.txt excluirá arquivos de texto apenas do diretório e **/*.txt excluirá arquivos de texto de todos os diretórios e subdiretórios.

Nas versões 1.5.0 e posteriores da CLI do GDK, você pode ver um aviso durante a compilação do componente quando excludes é definido no arquivo de configuração do GDK. Para desativar esse aviso, defina a variável de ambiente GDK_EXCLUDES_WARN_IGNORE comotrue.

A CLI do GDK sempre exclui os seguintes arquivos do arquivo zip:

  • O arquivo gdk-config.json

  • O arquivo da fórmula (recipe.json ou recipe.yaml)

  • Crie pastas, como greengrass-build

Os arquivos a seguir são excluídos por padrão. No entanto, você pode controlar quais desses arquivos são excluídos com a opção excludes.

  • Qualquer pasta que comece com o prefixo “test” (test*)

  • Todos os arquivos ocultos

  • A pasta node_modules.

Se você especificar a opção excludes, a CLI do GDK excluirá somente os arquivos definidos com a opção excludes. Se você não especificar a opção excludes, a CLI do GDK excluirá os arquivos e pastas padrão mencionados anteriormente.

zip_name

O nome do arquivo zip a ser usado ao criar um artefato zip durante o processo de compilação. Válido somente quando a build_system é zip. Se build_system estiver vazio, o nome do componente será usado para o nome do arquivo zip.

publish

A configuração a ser usada para publicar esse componente no serviço do AWS IoT Greengrass.

Se você usar a CLI do GDK v1.1.0 ou posterior, poderá especificar o argumento --bucket para especificar o bucket do S3 em que a CLI do GDK carrega os artefatos do componente. Se você não especificar esse argumento, a CLI do GDK será carregada no bucket do S3 cujo nome é bucket-region-accountId, em que bucket e região são os valores que você especifica em gdk-config.json, e accountId é seu ID da Conta da AWS. A CLI do GDK criará o bucket, se ele não existir.

Esse objeto contém as seguintes informações:

bucket

O nome do bucket do S3 a ser usado para hospedar artefatos de componentes.

region

A Região da AWS em que a CLI do GDK publica este componente.

Essa propriedade é opcional se você estiver usando a CLI do GDK v1.3.0 ou posterior.

options

(Opcional) Opções de configuração adicionais usadas durante o processo de compilação do componente.

Este atributo está disponível para a CLI do GDK v1.2.0 e posteriores.

file_upload_args

Uma estrutura JSON contendo argumentos enviados ao Amazon S3 durante o upload de arquivos para um bucket, como metadados e mecanismos de criptografia. Para ter uma lista dos argumentos permitidos, consulte a classe S3Transfer na documentação do Boto3.

test-e2e

(Opcional) A configuração a ser usada durante o teste ponta a ponta do componente. Este atributo está disponível para a CLI do GDK v1.3.0 e posteriores.

build

build_system: o sistema de compilação a ser usado. A opção padrão é maven. Escolha uma das seguintes opções:

  • maven: executa o comando mvn package para criar o módulo de teste. Escolha essa opção para criar o módulo de teste que usa o Maven.

  • gradle: executa o comando gradle build para criar o módulo de teste. Escolha essa opção para o módulo de teste que usa o Gradle.

gtf_version

(Opcional) A versão da estrutura de testes do Greengrass (GTF) a ser usada como dependência do módulo de teste de ponta a ponta ao inicializar o projeto do GDK com GTF. Esse valor deve ser uma das versões do GTF dos lançamentos. O padrão é GTF versão 1.1.0.

gtf_options

(Opcional) Opções de configuração adicionais usadas durante o teste de ponta a ponta do componente.

A lista a seguir inclui as opções que você pode usar com o GTF para a versão 1.1.0.

  • additional-plugins: (opcional) plug-ins adicionais do Cucumber

  • aws-region: tem como alvo endpoints regionais específicos para serviços da AWS. O padrão é o que o SDK da AWS descobre.

  • credentials-path: caminho opcional de credenciais do perfil da AWS. O padrão é credenciais descobertas no ambiente do host.

  • credentials-path-rotation: duração de rotação opcional para credenciais da AWS. O valor padrão é 15 minutos ou PT15M.

  • csr-path: o caminho para o CSR usando qual certificado do dispositivo será gerado.

  • device-mode: o dispositivo alvo em teste. O padrão é o dispositivo local.

  • env-stage: tem como alvo o ambiente de implantação do Greengrass. O padrão é produção.

  • existing-device-cert-arn: o arn de um certificado existente que você deseja usar como certificado de dispositivo para o Greengrass.

  • feature-path: arquivo ou diretório contendo arquivos de atributos adicionais. O padrão é não usar nenhum arquivo de atributo adicional.

  • gg-cli-version: substitui a versão da CLI do Greengrass. O padrão é o valor encontrado em ggc.version.

  • gg-component-bucket: o nome de um bucket existente do Amazon S3 que abriga os componentes do Greengrass.

  • gg-component-overrides: uma lista de substituições de componentes do Greengrass.

  • gg-persist: uma lista de elementos de teste a serem persistidos após a execução do teste. O comportamento padrão é não persistir em nada. Os valores aceitos são aws.resources, installed.software e generated.files.

  • gg-runtime: uma lista de valores para influenciar a forma como o teste interage com os recursos do teste. Esses valores substituem o parâmetro gg.persist. Se o padrão for vazio, ele presume que todos os recursos de teste são gerenciados pelo caso de teste, incluindo o runtime do Greengrass instalado. Os valores aceitos são aws.resources, installed.software e generated.files.

  • ggc-archive: o caminho para o componente do núcleo arquivado do Greengrass.

  • ggc-install-root: diretório para instalar o componente do núcleo do Greengrass. O padrão é test.temp.path e pasta de execução de teste.

  • ggc-log-level: defina o nível de log do núcleo do Greengrass para a execução do teste. O padrão é INFO.

  • ggc-tes-rolename: o perfil do IAM que o AWS IoT Greengrass Core assumirá para acessar os serviços da AWS. Se um perfil com o nome fornecido não existir, será criada uma política de acesso padrão.

  • ggc-trusted-plugins: a lista separada por vírgula dos caminhos (no host) dos plug-ins confiáveis que precisam ser adicionados ao Greengrass. Para fornecer o caminho no próprio DUT, prefixe o caminho com 'dut:'.

  • ggc-user-name: o valor de user:group PosixUser para o núcleo do Greengrass. O padrão é o nome de usuário atual que está conectado.

  • ggc-version: substitui a versão do componente do núcleo do Greengrass em execução. O padrão é o valor encontrado em ggc.archive.

  • log-level: nível de log da execução do teste. O padrão é “INFO”.

  • parallel-config: conjunto de índice de lote e número de lotes como uma string JSON. O valor padrão do índice do lote é 0 e o número de lotes é 1.

  • proxy-url: configura todos os testes para rotear o tráfego por meio desse URL.

  • tags: executa apenas tags de atributos. Pode ser cruzado com '&'

  • test-id-prefix: um prefixo comum aplicado a todos os recursos específicos do teste, incluindo nomes e tags de recursos da AWS. O padrão é um prefixo “gg”.

  • test-log-path: diretório que conterá os resultados de toda a execução do teste. O padrão é "testResults".

  • test-results-json: sinalize para determinar se um relatório JSON do Cucumber resultante foi gerado e gravado no disco. O valor padrão é verdadeiro.

  • test-results-log: sinalize para determinar se a saída do console foi gerada e gravada no disco. O padrão é falso.

  • test-results-xml: sinalize para determinar se um relatório XML JUnit resultante é gerado e gravado em disco. O padrão é verdadeiro.

  • test-temp-path: diretório para gerar artefatos de teste locais. O padrão é um diretório temporário aleatório prefixado com gg-testing.

  • timeout-multiplier: multiplicador fornecido para todos os tempos limite de teste. O padrão é 1.0.

Exemplos de arquivos de configuração da CLI do GDK

Você pode consultar os seguintes exemplos de arquivos de configuração da CLI do GDK para configurar ambientes de componentes do Greengrass.

Hello World (Python)

O arquivo de configuração da CLI do GDK a seguir é compatível com um componente Hello World que executa um script Python. Esse arquivo de configuração usa o sistema de compilação zip para empacotar o script Python do componente em um arquivo ZIP que a CLI do GDK carrega como um artefato.

{
  "component": {
    "com.example.PythonHelloWorld": {
      "author": "Amazon",
      "version": "NEXT_PATCH",
      "build": {
        "build_system" : "zip",
        "options": {
           "excludes": [".*"]
        }
      },
      "publish": {
        "bucket": "greengrass-component-artifacts",
        "region": "us-west-2",
        "options": {
           "file_upload_args": {
              "Metadata": {
                 "some-key": "some-value"
              }
           }
        }
      }
    },
  "test-e2e":{
    "build":{
        "build_system": "maven"
    },
    "gtf_version": "1.1.0",
    "gtf_options": { 
         "tags": "Sample"
     }
  },
  "gdk_version": "1.6.1"
  }
}

Hello World (Java)

O arquivo de configuração da CLI do GDK a seguir é compatível com um componente Hello World que executa uma aplicação Java. Este arquivo de configuração usa o sistema de compilação maven para empacotar o código-fonte Java do componente em um arquivo JAR que a CLI do GDK carrega como um artefato.

{
  "component": {
    "com.example.JavaHelloWorld": {
      "author": "Amazon",
      "version": "NEXT_PATCH",
      "build": {
        "build_system" : "maven"
      },
      "publish": {
        "bucket": "greengrass-component-artifacts",
        "region": "us-west-2",
        "options": {
           "file_upload_args": {
              "Metadata": {
                 "some-key": "some-value"
              }
           }
        }
      }
  },
  "test-e2e":{
    "build":{
        "build_system": "maven"
    },
    "gtf_version": "1.1.0",
    "gtf_options": { 
         "tags": "Sample"
     }
  },
  "gdk_version": "1.6.1"
  }
}

Componentes da comunidade

Vários componentes da comunidade no Catálogo do Software do Greengrass usam a CLI do GDK. Você pode explorar os arquivos de configuração da CLI do GDK nos repositórios desses componentes.

Para visualizar os arquivos de configuração da CLI do GDK dos componentes da comunidade

  1. Execute o seguinte comando para listar os componentes da comunidade que usam a CLI do GDK.

    gdk component list --repository

    A resposta lista o nome do repositório do GitHub para cada componente da comunidade que usa a CLI do GDK. Cada repositório existe na organização awslabs.

    [2022-02-22 17:27:31] INFO - Listing all the available component repositories from Greengrass Software Catalog.
[2022-02-22 17:27:31] INFO - Found '6' component repositories to display.
1. aws-greengrass-labs-database-influxdb
2. aws-greengrass-labs-telemetry-influxdbpublisher
3. aws-greengrass-labs-dashboard-grafana
4. aws-greengrass-labs-dashboard-influxdb-grafana
5. aws-greengrass-labs-local-web-server
6. aws-greengrass-labs-lookoutvision-gstreamer

  2. Abra o repositório GitHub de um componente da comunidade na seguinte URL. Substitua community-component-name pelo nome de um componente da comunidade da etapa anterior.

    https://github.com/awslabs/community-component-name