Greengrass Development Kit CLI configuration file
The Amazon IoT Greengrass Development Kit Command-Line Interface (GDK CLI) reads from a configuration file named
gdk-config.json
to build and publish components. This configuration file
must exist in the root of the component repository. You can use the GDK CLI init command to initialize
component repositories with this configuration file.
GDK CLI configuration file format
When you define a GDK CLI configuration file for a component, you specify the following information in JSON format.
gdk_version
-
The minimum version of the GDK CLI that is compatible with this component.
component
-
The configuration for this component.
componentName
-
author
-
The author or publisher of the component.
version
-
The version of the component. Specify one of the following:
-
NEXT_PATCH
– When you choose this option, the GDK CLI sets the version when you publish the component. The GDK CLI queries the Amazon IoT Greengrass service to identify the latest published version of the component. Then, it sets the version to the next patch version after that version. If you haven't published the component before, the GDK CLI uses version1.0.0
.If you choose this option, you can't use the Greengrass CLI to locally deploy and test the component to your local development computer that runs the Amazon IoT Greengrass Core software. To enable local deployments, you must specify a semantic version instead.
-
A semantic version, such as
1.0.0
. Semantic versions use a major.minor.patch numbering system. For more information, see the semantic version specification. If you develop components on a Greengrass core device where you want to deploy and test the component, choose this option. You must build the component with a specific version to create local deployments with the Greengrass CLI.
-
build
-
The configuration to use to build this component's source into artifacts. This object contains the following information:
-
build_system
-
The build system to use. Choose from the following options:
-
zip
– Packages the component's folder into a ZIP file to define as the component's only artifact. Choose this option for the following types of components:-
Components that use interpreted programming languages, such as Python or JavaScript.
-
Components that package files other than code, such as machine learning models or other resources.
The GDK CLI zips the component's folder into a zip file with the same name as the component folder. For example, if the component folder's name is
HelloWorld
, the GDK CLI creates a zip file namedHelloWorld.zip
.Note If you use GDK CLI version 1.0.0 on a Windows device, the component folder and zip file names must contain only lowercase letters.
When the GDK CLI zips the component's folder into a zip file, it skips the following files:
-
The
gdk-config.json
file -
The recipe file (
recipe.json
orrecipe.yaml
) -
Build folders, such as
greengrass-build
-
-
maven
– Runs themvn clean package
command to build the component's source into artifacts. Choose this option for components that use Maven, such as Java components. On Windows devices, this feature is available for GDK CLI v1.1.0 and later.
-
gradle
– Runs thegradle build
command to build the component's source into artifacts. Choose this option for components that use Gradle. This feature is available for GDK CLI v1.1.0 and later. The
gradle
build system supports Kotlin DSL as the build file. This feature is available for GDK CLI v1.2.0 and later. -
gradlew
– Runs thegradlew
command to build the component's source into artifacts. Choose this option for components that use the Gradle Wrapper. This feature is available for GDK CLI v1.2.0 and later.
-
custom
– Runs a custom command to build the component's source into a recipe and artifacts. Specify the custom command in thecustom_build_command
parameter.
-
custom_build_command
-
(Optional) The custom build command to run for a custom build system. You must specify this parameter if you specify
custom
forbuild_system
.Important This command must create a recipe and artifacts in the following folders within the component folder. The GDK CLI creates these folders for you when you run the component build command.
-
Recipe folder:
greengrass-build/recipes
-
Artifacts folder:
greengrass-build/artifacts/
componentName
/componentVersion
Replace
componentName
with the component name, and replacecomponentVersion
with the component version orNEXT_PATCH
.
You can specify a single string or a list of strings, where each string is a word in the command. For example, to run a custom build command for a C++ component, you might specify
cmake --build build --config Release
or["cmake", "--build", "build", "--config", "Release"]
.To view an example of a custom build system, see the aws.greengrass.labs.LocalWebServer community component on GitHub
. -
options
-
(Optional) Additional configuration options used during component build process.
This feature is available for GDK CLI v1.2.0 and later.
excludes
-
A list of file patterns that define the files that should be excluded from the zip file. Only valid when the
build_system
iszip
.The following files are always excluded from the zip file:
-
The
gdk-config.json
file -
The recipe file (
recipe.json
orrecipe.yamal
) -
Build folders such as
greengrass-build
-
-
publish
-
The configuration to use to publish this component to the Amazon IoT Greengrass service.
If you use GDK CLI v1.1.0 or later, you can specify the
--bucket
argument to specify the S3 bucket where the GDK CLI uploads the component's artifacts. If you don't specify this argument, the GDK CLI uploads to the S3 bucket whose name is
, wherebucket
-region
-accountId
bucket
andregion
are the values that you specify ingdk-config.json
, andaccountId
is your Amazon Web Services account ID. The GDK CLI creates the bucket if it doesn't exist.This object contains the following information:
bucket
-
The S3 bucket name to use to host component artifacts.
region
-
The Amazon Web Services Region where the GDK CLI publishes this component.
options
-
(Optional) Additional configuration options used during component version creation.
This feature is available for GDK CLI v1.2.0 and later.
file_upload_args
-
A JSON structure containing arguments sent to Amazon S3 while uploading files to a bucket, such as metadata and encryption mechanisms. For a list of the allowed arguments, see the
S3Transfer
class in the Boto3 documentation..
GDK CLI configuration file examples
You can reference the following GDK CLI configuration file examples to help you configure Greengrass component environments.
Hello World (Python)
The following GDK CLI configuration file supports a Hello World component that runs a
Python script. This configuration file uses the zip
build system to package the
component's Python script into a ZIP file that the GDK CLI uploads as an artifact.
{ "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
" } } } } } }, "gdk_version": "1.2.0" }
Hello World (Java)
The following GDK CLI configuration file supports a Hello World component that runs a
Java application. This configuration file uses the maven
build system to
package the component's Java source code into a JAR file that the GDK CLI uploads as an
artifact.
{ "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
" } } } } } }, "gdk_version": "1.2.0" }
Community components
Several community components in the Greengrass Software Catalog use the GDK CLI. You can explore the GDK CLI configuration files in these components' repositories.
To view community components' GDK CLI configuration files
-
Run the following command to list the community components that use the GDK CLI.
gdk component list --repository
The response lists the name of the GitHub repository for each community component that uses the GDK CLI. Each repository exists in the
awslabs
organization.[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
-
Open a community component's GitHub repository at the following URL. Replace
community-component-name
with the name of a community component from the previous step.https://github.com/awslabs/
community-component-name