Archivo de configuración la CLI del kit de desarrollo de Greengrass - AWS IoT Greengrass
Formato de archivo de configuración de la CLI del GDKEjemplos de archivo de configuración de la CLI del GDK

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Archivo de configuración la CLI del kit de desarrollo de Greengrass

La interfaz de línea de comandos del kit de desarrollo de AWS IoT Greengrass (CLI del GDK) lee un archivo de configuración denominado gdk-config.json para crear y publicar componentes. Este archivo de configuración debe estar en la raíz del repositorio del componente. Puede utilizar el comando init de la CLI del GDK para inicializar los repositorios de componentes con este archivo de configuración.

Formato de archivo de configuración de la CLI del GDK

Al definir un archivo de configuración de la CLI del GDK para un componente, se especifica la siguiente información en formato JSON.

gdk_version

La versión mínima de la CLI del GDK que es compatible con este componente. Este valor debe ser una de las versiones de la CLI del GDK de los lanzamientos.

component

La configuración de este componente.

componentName
author

El autor o publicador del componente.

version

Esta es la versión del componente. Especifique uno de los siguientes valores:

  • NEXT_PATCH: al elegir esta opción, la CLI de GDK establece la versión al publicar el componente. La CLI de GDK consulta el servicio de AWS IoT Greengrass para identificar la versión más reciente publicada del componente. A continuación, establece la versión en la siguiente versión del parche posterior a esa versión. Si no ha publicado el componente antes, la CLI de GDK usa la versión 1.0.0.

    Si elige esta opción, no podrá usar la CLI de Greengrass para implementar y probar localmente el componente en su computadora de desarrollo local que ejecuta el software AWS IoT Greengrass Core. Para habilitar las implementaciones locales, debe especificar una versión semántica en su lugar.

  • Una versión semántica, como 1.0.0. Las versiones semánticas siguen un sistema de números de major.minor.patch. Para obtener más información, consulte la especificación semántica de la versión.

    Si desarrolla componentes en un dispositivo principal de Greengrass en el que desee implementar y probar el componente, elija esta opción. Debe compilar el componente con una versión específica para crear implementaciones locales con la CLI de Greengrass.

build

La configuración que se utilizará para convertir el origen de este componente en artefactos. Este objeto contiene la siguiente información:

build_system

El sistema de compilación que se va a utilizar. Puede elegir entre las siguientes opciones:

  • zip: empaqueta la carpeta del componente en un archivo ZIP para definirla como el único artefacto del componente. Elija esta opción para los siguientes tipos de componentes:

    • Componentes que usan lenguajes de programación interpretados, como Python o JavaScript.

    • Componentes que empaquetan archivos distintos del código, como modelos de machine learning u otros recursos.

    La CLI de GDK comprime la carpeta del componente en un archivo zip con el mismo nombre que la carpeta del componente. Por ejemplo, si el nombre de la carpeta del componente es HelloWorld, la CLI de GDK crea un archivo zip denominado HelloWorld.zip.

    nota

    Si usa la versión 1.0.0 de la CLI de GDK en un dispositivo Windows, los nombres de las carpetas y los archivos zip de los componentes deben contener solo letras minúsculas.

    Cuando la CLI de GDK comprime la carpeta del componente en un archivo zip, omite los siguientes archivos:

    • El archivo gdk-config.json

    • El archivo de receta (recipe.json o recipe.yaml)

    • Carpetas de compilación, como greengrass-build

  • maven: ejecuta el comando mvn clean package para compilar el origen del componente en artefactos. Elija esta opción para los componentes que usan Maven, como los componentes de Java.

    En dispositivos Windows, esta característica está disponible para la versión 1.1.0 y posteriores de la CLI de GDK.

  • gradle: ejecuta el comando gradle build para compilar el origen del componente en artefactos. Elija esta opción para los componentes que usan Gradle. Esta característica está disponible para la versión 1.1.0 y posteriores de la CLI de GDK.

    El sistema de compilación gradle admite Kotlin DSL como archivo de compilación. Esta característica está disponible para la versión 1.2.0 y versiones posteriores de la CLI de GDK.

  • gradlew: ejecuta el comando gradlew para compilar el origen del componente en artefactos. Elija esta opción para los componentes que usan el Gradle Wrapper.

    Esta característica está disponible para la versión 1.2.0 y versiones posteriores de la CLI de GDK.

  • custom: ejecuta un comando personalizado para compilar el origen del componente en una receta y artefactos. Especifique el comando personalizado en el parámetro custom_build_command.

custom_build_command

(Opcional) El comando de compilación personalizado que se ejecuta en un sistema de compilación personalizado. Debe especificar este parámetro si especifica custom para build_system.

importante

Este comando debe crear una receta y artefactos en las siguientes carpetas de la carpeta del componente. La CLI de GDK crea estas carpetas automáticamente al ejecutar el comando component build.

  • Carpeta de recetas: greengrass-build/recipes

  • Carpeta de artefactos: greengrass-build/artifacts/componentName/componentVersion

    Sustituya componentName por el nombre del componente y sustituya componentVersion por la versión del componente o NEXT_PATCH.

Puede especificar una sola cadena o una lista de cadenas, donde cada cadena es una palabra del comando. Por ejemplo, para ejecutar un comando de compilación personalizado para un componente de C++, puede especificar cmake --build build --config Release o ["cmake", "--build", "build", "--config", "Release"].

Para ver un ejemplo de un sistema de compilación personalizado, consulte aws.greengrass.labs.LocalWebServer community component en GitHub.

options

(Opcional) Se utilizan opciones de configuración adicionales durante el proceso de creación del componente.

Esta característica está disponible para la versión 1.2.0 y versiones posteriores de la CLI de GDK.

excludes

Una lista de patrones globales que definen qué archivos se deben excluir del directorio de componentes al crear el archivo zip. Válido solo cuando build_system es zip.

nota

En las versiones 1.4.0 y anteriores de la CLI del GDK, cualquier archivo que coincida con una entrada de la lista de exclusiones se excluye de todos los subdirectorios del componente. Para lograr el mismo comportamiento en las versiones 1.5.0 y posteriores de la CLI del GDK, anteponga **/ a las entradas existentes en la lista de exclusiones. Por ejemplo, *.txt excluirá los archivos de texto solo del directorio; **/*.txt excluirá los archivos de texto de todos los directorios y subdirectorios.

En las versiones 1.5.0 y posteriores de la CLI del GDK, es posible que vea una advertencia durante la compilación del componente cuando excludes esté definido en el archivo de configuración del GDK. Para deshabilitar esta advertencia, defina la variable de entorno GDK_EXCLUDES_WARN_IGNORE en true.

La CLI del GDK siempre excluye los siguientes archivos del archivo zip:

  • El archivo gdk-config.json

  • El archivo de receta (recipe.json o recipe.yaml)

  • Carpetas de compilación, como greengrass-build

De forma predeterminada, se excluyen los siguientes archivos. Sin embargo, puede controlar cuáles de estos archivos se excluyen con la opción excludes.

  • Cualquier carpeta que comience con el prefijo “test” (test*)

  • Todos los archivos ocultos

  • La carpeta node_modules

Si especifica la opción excludes, la CLI del GDK excluirá solo los archivos que configuró con la opción excludes. Si no especifica la opción excludes, la CLI del GDK excluye los archivos y carpetas predeterminados indicados anteriormente.

zip_name

El nombre del archivo zip que se utilizará al crear un artefacto zip durante el proceso de creación. Válido solo cuando build_system es zip. Si build_system está vacío, el nombre del componente se utiliza como nombre del archivo zip.

publish

La configuración que se utilizará para publicar este componente en el servicio de AWS IoT Greengrass.

Si usa la versión 1.1.0 o posteriores de la CLI de GDK, puede especificar el argumento --bucket para especificar el bucket de S3 en el que la CLI de GDK carga los artefactos del componente. Si no especifica este argumento, la CLI de GDK se carga en el bucket de S3 cuyo nombre es bucket-region-accountId, donde bucket y region son los valores que especifica en gdk-config.json y acountId es el ID de su Cuenta de AWS. La CLI de GDK crea el bucket si no existe.

Este objeto contiene la siguiente información:

bucket

El nombre del bucket de S3 que se utilizará para alojar los artefactos de los componentes.

region

La Región de AWS donde la CLI del GDK publica este componente.

Esta propiedad es opcional si utiliza la CLI del GDK versión 1.3.0 o versiones posteriores.

options

(Opcional) Se utilizan opciones de configuración adicionales durante la creación de la versión del componente.

Esta característica está disponible para la versión 1.2.0 y versiones posteriores de la CLI de GDK.

file_upload_args

Una estructura JSON que contiene argumentos que se envían a Amazon S3 al cargar archivos a un bucket, como metadatos y mecanismos de cifrado. Para obtener una lista de los argumentos permitidos, consulte la clase S3Transfer en la documentación de Boto3.

test-e2e

(Opcional) La configuración que se utilizará durante las pruebas integrales del componente. Esta característica está disponible para la CLI del GDK de versión 1.3.0 y versiones posteriores.

build

build_system: el sistema de compilación que se va a utilizar. La opción predeterminada es maven. Puede elegir entre las siguientes opciones:

  • maven: ejecuta el comando mvn package para compilar el módulo de pruebas. Elija esta opción para compilar el módulo de pruebas que usa Maven.

  • gradle: ejecuta el comando gradle build para compilar el módulo de pruebas. Elige esta opción para el módulo de pruebas que usa Gradle.

gtf_version

(Opcional) La versión del Greengrass Testing Framework (GTF) que se utilizará como dependencia del módulo de pruebas de extremo a extremo al inicializar el proyecto GDK con GTF. Este valor debe ser una de las versiones del GTF de los lanzamientos. El valor predeterminado es la versión 1.1.0 de GTF.

gtf_options

(Opcional) Opciones de configuración adicionales utilizadas durante las pruebas integrales del componente.

En la siguiente lista, se incluyen las opciones que puede utilizar con la versión 1.1.0 de GTF.

  • additional-plugins: (opcional) complementos de Cucumber adicionales

  • aws-region: apunta a puntos de conexión regionales específicos para los servicios de AWS. El valor predeterminado es lo que detecta el SDK de AWS.

  • credentials-path: ruta de credenciales de perfil de AWS opcional. El valor predeterminado son las credenciales detectadas en el entorno host.

  • credentials-path-rotation: duración de rotación opcional para las credenciales de AWS. El valor predeterminado es de 15 minutos o PT15M.

  • csr-path: la ruta de la CSR mediante la cual se generará el certificado del dispositivo.

  • device-mode: el dispositivo objetivo que se está probando. El valor predeterminado es el dispositivo local.

  • env-stage: apunta al entorno de implementación de Greengrass. El valor predeterminado es de producción.

  • existing-device-cert-arn: el ARN de un certificado existente que desee usar como certificado de dispositivo para Greengrass.

  • feature-path: archivo o directorio que contiene archivos de características adicionales. El valor predeterminado es que no se usan archivos de características adicionales.

  • gg-cli-version: anula la versión de la CLI de Greengrass. El valor predeterminado es el que se encuentra en ggc.version.

  • gg-component-bucket: el nombre de un bucket de Amazon S3 existente que aloja los componentes de Greengrass.

  • gg-component-overrides: una lista de anulaciones de componentes de Greengrass.

  • gg-persist: una lista de elementos de prueba que persisten tras una ejecución de la prueba. El comportamiento predeterminado es no conservar nada. Los valores aceptados son: aws.resources, installed.software y generated.files.

  • gg-runtime: una lista de valores para influir en la forma en que la prueba interactúa con los recursos de la prueba. Estos valores sustituyen al parámetro gg.persist. Si el valor predeterminado está vacío, se asume que todos los recursos de prueba se administran por caso de prueba, incluido el tiempo de ejecución de Greengrass instalado. Los valores aceptados son: aws.resources, installed.software y generated.files.

  • ggc-archive: la ruta hacia el componente del núcleo de Greengrass archivado.

  • ggc-install-root: directorio para instalar el componente núcleo de Greengrass. Los valores predeterminados son test.temp.path y la carpeta de ejecución de la prueba.

  • ggc-log-level: establece el nivel de registro del núcleo de Greengrass para la ejecución de la prueba. El valor predeterminado es “INFO”.

  • ggc-tes-rolename: el rol de IAM que asumirá AWS IoT Greengrass Core para acceder a los servicios de AWS. Si no existe un rol con un nombre dado, se creará uno con una política de acceso predeterminada.

  • ggc-trusted-plugins: la lista separada por comas de las rutas (en el host) de los complementos de confianza que deben agregarse a Greengrass. Para indicar la ruta en el propio DUT, agregue el prefijo “dut:” a la ruta

  • ggc-user-name: el valor user:group posixUser para el núcleo de Greengrass. El valor predeterminado es el nombre de usuario actual con el que se ha iniciado sesión.

  • ggc-version: anula la versión del componente núcleo de Greengrass en ejecución. El valor predeterminado es el que se encuentra en ggc.archive.

  • log-level: nivel de registro de la ejecución de la prueba. El valor predeterminado es “INFO”.

  • parallel-config: conjunto de índices de lotes y número de lotes como cadena JSON. El valor predeterminado del índice de lotes es 0 y el número de lotes es 1.

  • proxy-url: configura todas las pruebas para enrutar el tráfico a través de esta URL.

  • tags: ejecuta únicamente etiquetas de características. Se puede intersecar con “&”

  • test-id-prefix: un prefijo común que se aplica a todos los recursos específicos de la prueba, incluidos los nombres y las etiquetas de los recursos de AWS. El prefijo predeterminado es “gg”.

  • test-log-path: directorio que contendrá los resultados de toda la ejecución de la prueba. El valor predeterminado es “testResults”.

  • test-results-json: marcador para determinar si se genera un informe JSON de Cucumber resultante escrito en el disco. El valor predeterminado es true (verdadero).

  • test-results-log: marcador para determinar si la salida de la consola se genera escrita en el disco. El valor predeterminado es falso.

  • test-results-xml: marcador para determinar si se genera un informe XML de JUnit resultante escrito en el disco. El valor predeterminado es true (verdadero).

  • test-temp-path: directorio para generar artefactos de prueba locales. El valor predeterminado es un directorio temporal aleatorio con el prefijo gg-testing.

  • timeout-multiplier: multiplicador proporcionado para todos los tiempos de espera de las pruebas. El valor predeterminado es 1.0.

Ejemplos de archivo de configuración de la CLI del GDK

Puede hacer referencia a los siguientes ejemplos de archivos de configuración de la CLI del GDK para ayudarlo a configurar los entornos de componentes de Greengrass.

Hello World (Python)

El siguiente archivo de configuración de la CLI del GDK admite un componente Hello world que ejecuta un script de Python. Este archivo de configuración utiliza el sistema de compilación zip para empaquetar el script de Python del componente en un archivo ZIP que la CLI del GDK carga como un artefacto.

{
  "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)

El siguiente archivo de configuración de la CLI del GDK admite un componente Hello world que ejecuta una aplicación Java. Este archivo de configuración utiliza el sistema de compilación maven para empaquetar el código de origen Java del componente en un archivo JAR que la CLI de GDK carga como un artefacto.

{
  "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 de la comunidad

Varios componentes de la comunidad del catálogo de software de Greengrass utilizan la CLI del GDK. Puede explorar los archivos de configuración de la CLI del GDK en los repositorios de estos componentes.

Cómo ver los archivos de configuración de la CLI del GDK de los componentes de la comunidad

  1. Ejecute el siguiente comando para mostrar en una lista los componentes de la comunidad que utilizan la CLI del GDK.

    gdk component list --repository

    La respuesta muestra el nombre del repositorio de GitHub para cada componente de la comunidad que usa la CLI del GDK. Cada repositorio existe en la organización 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 el repositorio de GitHub de un componente de la comunidad en la siguiente URL. Sustituya community-component-name por el nombre de un componente de la comunidad del paso anterior.

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