Greengrass 开发套件 CLI 配置文件 - AWS IoT Greengrass

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

Greengrass 开发套件 CLI 配置文件

AWS IoT Greengrass开发套件命令行接口 (GDK CLI) 从gdk-config.json名为的配置文件中读取数据以生成和发布组件。此配置文件必须存在于组件存储库的根目录中。您可以使用 GDK CLI init 命令使用此配置文件初始化组件存储库。

GDK CLI 配置文件格式

在为组件定义 GDK CLI 配置文件时,需要以 JSON 格式指定以下信息。

gdk_version

与此组件兼容的 GDK CLI 的最低版本。此值必须是发行版中的 GDK CLI 版本之一。

component

此组件的配置。

componentName
author

组件的作者或发布者。

version

组件版本。指定下列项之一:

  • NEXT_PATCH— 当您选择此选项时,GDK CLI 将在您发布组件时设置版本。GDK CLI 会查询AWS IoT Greengrass服务以识别该组件的最新发布版本。然后,它将版本设置为该版本之后的下一个补丁版本。如果您之前没有发布过该组件,GDK CLI 将使用版本1.0.0

    如果选择此选项,则无法使用 Greengrass CLI 在本地部署该组件并将其测试到运行 Core 软件的本地开发计算机上。AWS IoT Greengrass要启用本地部署,必须改为指定语义版本。

  • 语义版本,例如。1.0.0语义版本使用主调未成年人补丁编号系统。有关更多信息,请参阅语义版本规范

    如果您在 Greengrass 核心设备上开发要部署和测试该组件的组件,请选择此选项。要使用 Greengr ass CLI 创建本地部署,必须使用特定版本构建组件。

build

用于将此组件的源代码构建为工件的配置。该对象包含以下信息:

build_system

要使用的构建系统。从以下选项中进行选择:

  • zip— 将组件的文件夹打包为 ZIP 文件以定义为该组件的唯一构件。为以下类型的组件选择此选项:

    • 使用解释型编程语言的组件,例如 Python 或 JavaScript。

    • 打包除代码之外的文件的组件,例如机器学习模型或其他资源。

    GDK CLI 将组件的文件夹压缩为与组件文件夹同名的 zip 文件。例如,如果组件文件夹的名称为HelloWorld,则 GDK CLI 会创建一个名HelloWorld.zip为的 zip 文件。

    注意

    如果您在 Windows 设备上使用 GDK CLI 版本 1.0.0,则组件文件夹和 zip 文件名必须仅包含小写字母。

    当 GDK CLI 将组件的文件夹压缩为 zip 文件时,它会跳过以下文件:

    • gdk-config.json 文件

    • 配方文件(recipe.jsonrecipe.yaml

    • 生成文件夹,例如 greengrass-build

  • maven— 运行mvn clean package命令将组件的源代码构建为工件。对于使用 Mave n 的组件(例如 Java 组件),请选择此选项。

    在 Windows 设备上,此功能适用于 GDK CLI v1.1.0 及更高版本。

  • gradle— 运行gradle build命令将组件的源代码构建为工件。对于使用 Gradle 的组件,请选择此选项。此功能适用于 GDK CLI 版本 1.1.0 及更高版本。

    gradle译系统支持 Kotlin DSL 作为构建文件。此功能适用于 GDK CLI 版本 1.2.0 及更高版本。

  • gradlew— 运行gradlew命令将组件的源代码构建为工件。对于使用 Gradle 包装器的组件,请选择此选项。

    此功能适用于 GDK CLI 版本 1.2.0 及更高版本。

  • custom— 运行自定义命令将组件的源代码构建为配方和工件。在custom_build_command参数中指定自定义命令。

custom_build_command

(可选)要为自定义编译系统运行的自定义编译命令。如果为指定,则必须指定custom此参数build_system

重要

此命令必须在组件文件夹的以下文件夹中创建配方和工件。当您运行组件构建命令时,GDK CLI 会为您创建这些文件夹。

  • 食谱文件夹:greengrass-build/recipes

  • 工件文件夹:greengrass-build/artifacts/componentName/componentVersion

    componentName 替换为组件名称,并将 componentVersion 替换为组件版本或。NEXT_PATCH

您可以指定单个字符串或字符串列表,其中每个字符串都是命令中的一个单词。例如,要为 C++ 组件运行自定义生成命令,可以指定cmake --build build --config Release["cmake", "--build", "build", "--config", "Release"]

要查看自定义编译系统的示例,请参阅aws.greengrass.labs.LocalWebServer community component上的 GitHub。

options

(可选)在组件构建过程中使用的其他配置选项。

此功能适用于 GDK CLI 版本 1.2.0 及更高版本。

excludes

glob 模式列表,用于定义构建 zip 文件时要从组件目录中排除哪些文件。仅在为时build_system有效zip

注意

在 GDK CLI 版本 1.4.0 及更早版本中,任何与排除列表中的条目相匹配的文件都将从组件的所有子目录中排除。要在 GDK CLI 版本 1.5.0 及更高版本中实现相同的行为,请在排除列表中的现有条目前**/面加上。例如,*.txt将仅从目录中排除文本文件;**/*.txt将从所有目录和子目录中排除文本文件。

在 GDK CLI 版本 1.5.0 及更高版本中,当在 GDK 配置文件中定义时excludes,您可能会在组件构建期间看到警告。要禁用此警告,请将环境变量设置GDK_EXCLUDES_WARN_IGNOREtrue

GDK CLI 始终从 zip 文件中排除以下文件:

  • gdk-config.json 文件

  • 配方文件(recipe.jsonrecipe.yaml

  • 生成文件夹,例如 greengrass-build

默认情况下,不包括以下文件。但是,您可以使用该excludes选项控制将哪些文件排除在外。

  • 任何以前缀 “test” (test*) 开头的文件夹

  • 所有隐藏的文件

  • node_modules 文件夹

如果您指定该excludes选项,GDK CLI 将仅排除您使用该excludes选项设置的文件。如果您未指定该excludes选项,GDK CLI 将排除前面提到的默认文件和文件夹。

zip_name

在生成过程中创建 zip 工件时使用的 zip 文件名。仅在为时build_system有效zip。如果为build_system空,则使用组件名称作为 zip 文件名。

publish

用于将此组件发布到AWS IoT Greengrass服务的配置。

如果您使用 GDK CLI v1.1.0 或更高版本,则可以指定--bucket参数来指定 GDK CLI 上传组件工件的 S3 存储桶。如果您不指定此参数,GDK CLI 会上传到名称为bucket-region-accountId、其中存储区域是您在中gdk-config.json指定的值,accountID 是您的 ID。 AWS 账户如果存储桶不存在,GDK CLI 会创建该存储桶。

该对象包含以下信息:

bucket

用于托管组件工件的 S3 存储桶名称。

region

GDK CLI 发布此组件AWS 区域的位置。

如果您使用的是 GDK CLI 1.3.0 或更高版本,则此属性是可选的。

options

(可选)创建组件版本期间使用的其他配置选项。

此功能适用于 GDK CLI 版本 1.2.0 及更高版本。

file_upload_args

一种 JSON 结构,包含在将文件上传到存储桶时发送到 Amazon S3 的参数,例如元数据和加密机制。有关允许的参数的列表,请参阅 Boto3 文档中的S3Transfer类。 。

test-e2e

(可选) end-to-end 测试组件期间要使用的配置。此功能适用于 GDK CLI 版本 1.3.0 及更高版本。

build

build_system— 要使用的构建系统。默认选项是maven。从以下选项中进行选择:

  • maven— 运行mvn package命令以生成测试模块。选择此选项来构建使用 Maven 的测试模块。

  • gradle— 运行gradle build命令以生成测试模块。为使用 Gradle 的测试模块选择此选项。

gtf_version

(可选)使用 GTF 初始化 GDK 项目时,用作测试模块依赖项的 Greengrass 测试框架 (GTF) 版本。 end-to-end 此值必须是发行版中的 GTF 版本之一。默认为 GTF 版本 1.1.0。

gtf_options

(可选) end-to-end 测试组件期间使用的其他配置选项。

以下列表包括您可以在 GTF 版本 1.1.0 中使用的选项。

  • additional-plugins—(可选)其他黄瓜插件

  • aws-region— 针对特定的区域AWS服务端点。默认为 S AWS DK 发现的内容。

  • credentials-path— 可选的AWS配置文件凭据路径。默认为在主机环境中发现的凭据。

  • credentials-path-rotation— AWS 证书的可选轮换持续时间。默认为 15 分钟或PT15M

  • csr-path— 用于生成设备证书的 CSR 路径。

  • device-mode— 正在测试的目标设备。默认为本地设备。

  • env-stage— 瞄准 Greengrass 的部署环境。默认为生产。

  • existing-device-cert-arn— 要用作 Greengrass 设备证书的现有证书的 arn。

  • feature-path— 包含其他功能文件的文件或目录。默认为不使用其他功能文件。

  • gg-cli-version— 覆盖 Greengrass CLI 的版本。默认为中找到的值ggc.version

  • gg-component-bucket— 存放 Greengrass 组件的现有 Amazon S3 存储桶的名称。

  • gg-component-overrides— Greengrass 组件重写列表。

  • gg-persist— 测试运行后要保留的测试元素列表。默认行为是不保留任何内容。可接受的值为:aws.resourcesinstalled.software、和generated.files

  • gg-runtime— 影响测试与测试资源交互方式的值列表。这些值取代参数。gg.persist如果默认值为空,则假设所有测试资源都由测试用例管理,包括已安装的 Greengrass 运行时。可接受的值为:aws.resourcesinstalled.software、和generated.files

  • ggc-archive— 存档的 Greengrass 核组件的路径。

  • ggc-install-root— 用于安装 Greengrass nucleus 组件的目录。默认为 test.temp.path 和测试运行文件夹。

  • ggc-log-level— 为测试运行设置 Greengrass nucleus 日志级别。默认为 “信息”。

  • ggc-tes-rolename— AWS IoT Greengrass Core 将担任的访问AWS服务的 IAM 角色。如果不存在具有给定名称的角色,则将创建一个默认访问策略。

  • ggc-trusted-plugins— 需要添加到 Greengrass 的可信插件的路径(主机上)的逗号分隔列表。要提供 DUT 本身的路径,请在路径前面加上 'dut: '

  • ggc-user-name— Greengrass 核的 user: group posixUser 值。默认为当前登录的用户名。

  • ggc-version— 覆盖正在运行的 Greengrass nucleus 组件的版本。默认为 ggc.archive 中找到的值。

  • log-level— 测试运行的日志级别。默认为 “信息”。

  • parallel-config— 将批次索引和批次数设置为 JSON 字符串。批次索引的默认值为 0,批次数为 1。

  • proxy-url— 将所有测试配置为通过此 URL 路由流量。

  • tags— 仅运行功能标签。可以与 '&' 相交

  • test-id-prefix— 适用于所有测试特定资源(包括AWS资源名称和标签)的通用前缀。默认为 “gg” 前缀。

  • test-log-path— 将包含整个测试运行结果的目录。默认为 “测试结果”。

  • test-results-json— 用于确定生成的 Cucumber JSON 报告是否已写入磁盘的标志。默认值为 true。

  • test-results-log— 用于确定控制台输出是否生成的写入磁盘的标志。默认值为 false。

  • test-results-xml— 用于确定生成的 JUnit XML 报告是否已写入磁盘的标志。默认值为 true。

  • test-temp-path— 生成本地测试工件的目录。默认为以 gg-testing 为前缀的随机临时目录。

  • timeout-multiplier— 为所有测试超时提供乘数。默认值为 1.0。

GDK CLI 配置文件示例

您可以参考以下 GDK CLI 配置文件示例来帮助您配置 Greengrass 组件环境。

你好世界 (Python)

以下 GDK CLI 配置文件支持运行 Python 脚本的 Hello World 组件。此配置文件使用编zip译系统将组件的 Python 脚本打包为 ZIP 文件,GDK CLI 将其作为构件上传。

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

你好 World (Java)

以下 GDK CLI 配置文件支持运行 Java 应用程序的 Hello World 组件。此配置文件使用编maven译系统将组件的 Java 源代码打包到 JAR 文件中,GDK CLI 将其作为构件上传。

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

社区组件

Greengrass 软件目录中的几个社区组件使用 GD K CLI。您可以浏览这些组件存储库中的 GDK CLI 配置文件。

查看社区组件的 GDK CLI 配置文件
  1. 运行以下命令列出使用 GDK CLI 的社区组件。

    gdk component list --repository

    响应列出了使用 GDK CLI 的每个社区组件的 GitHub 存储库名称。每个存储库都存在于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. 通过以下 URL 打开社区组件的 GitHub 存储库。community-component-name替换为上一步中的社区组件的名称。

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