# AWS IoT Greengrass development tools
Use AWS IoT Greengrass development tools to create, test, build, publish, and deploy custom Greengrass components.
+ **[Greengrass Development Kit CLI](greengrass-development-kit-cli.md)**
Use the AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) in your local development environment to create components from templates and community components in the [Greengrass Software Catalog](greengrass-software-catalog.md). You can use the GDK CLI to build the component and publish the component to the AWS IoT Greengrass service as a private component in your AWS account.
+ **[Greengrass Command Line Interface](gg-cli.md)**
Use the Greengrass Command Line Interface (Greengrass CLI) on Greengrass core devices to deploy and debug Greengrass components. The Greengrass CLI is a component that you can deploy to your core devices to create local deployments, view details about installed components, and explore log files.
+ **[Local debug console](local-debug-console-component.md)**
Use the local debug console on Greengrass core devices to deploy and debug Greengrass components using a local dashboard web interface. The local debug console is a component that you can deploy to your core devices to create local deployments and view details about installed components.
AWS IoT Greengrass also provides the following SDKs that you can use in custom Greengrass components:
+ The AWS IoT Device SDK and the AWS IoT Greengrass Component SDK, which contain the interprocess communication (IPC) library. For more information, see [Use the AWS IoT Device SDK to communicate with the Greengrass nucleus, other components, and AWS IoT CoreCommunicate with the Greengrass nucleus, other components, and AWS IoT Core](interprocess-communication.md).
+ The Stream Manager SDK, which you can use to transfer data streams to the AWS Cloud. For more information, see [Manage data streams on Greengrass core devices](manage-data-streams.md).
**Topics**
+ [AWS IoT Greengrass Development Kit Command-Line Interface](greengrass-development-kit-cli.md)
+ [Greengrass Command Line Interface](gg-cli.md)
+ [Use AWS IoT Greengrass Testing Framework](gg-testing-framework.md)
# AWS IoT Greengrass Development Kit Command-Line Interface
The AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) provides features that help you develop [custom Greengrass components](develop-greengrass-components.md). You can use the GDK CLI to create, build, and publish custom components. When you create a component repository with the GDK CLI, you can start from a template or a community component from the [Greengrass Software Catalog](greengrass-software-catalog.md). Then, you can choose a build system that packages files as ZIP archives, uses a Maven or Gradle build script, or runs a custom build command. After you create a component, you can use the GDK CLI to publish it to the AWS IoT Greengrass service, so you can use the AWS IoT Greengrass console or API to deploy the component to your Greengrass core devices.
When you develop Greengrass components without the GDK CLI, you must update the version and artifact URIs in the [component recipe file](component-recipe-reference.md) each time you create a new version of the component. When you use the GDK CLI, it can automatically update the version and artifact URIs for you each time you publish a new version of the component.
The GDK CLI is open source and available on GitHub. You can customize and extend the GDK CLI to meet your component development needs. We invite you to open issues and pull requests on the GitHub repository. You can find the GDK CLI source at the following link: [https://github.com/aws-greengrass/aws-greengrass-gdk-cli](https://github.com/aws-greengrass/aws-greengrass-gdk-cli).
## Prerequisites
To install and use the Greengrass Development Kit CLI, you need the following:
+ An AWS account. If you don't have one, see [Set up an AWS account](setting-up.md#set-up-aws-account).
+ A Windows, macOS, or Unix-like development computer with an internet connection.
+ For GDK CLI version 1.1.0 or later, [Python](https://www.python.org/downloads/) 3.6 or later installed on your development computer.
For GDK CLI version 1.0.0, [Python](https://www.python.org/downloads/) 3.8 or later installed on your development computer.
+ [Git](https://git-scm.com/) installed on your development computer.
+ AWS Command Line Interface (AWS CLI) installed and configured with credentials on your development computer. For more information, see [Installing, updating, and uninstalling the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) and [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) in the *AWS Command Line Interface User Guide*.
**Note**
If you use a Raspberry Pi or another 32-bit ARM device, install AWS CLI V1. AWS CLI V2 isn't available for 32-bit ARM devices. For more information, see [Installing, updating, and uninstalling the AWS CLI version 1](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv1.html).
+ To use the GDK CLI to publish components to the AWS IoT Greengrass service, you must have the following permissions:
+ `s3:CreateBucket`
+ `s3:GetBucketLocation`
+ `s3:PutObject`
+ `greengrass:CreateComponentVersion`
+ `greengrass:ListComponentVersions`
+ To use the GDK CLI to build a component whose artifacts exist in an S3 bucket and not in the local file system, you must have the following permissions:
+ `s3:ListBucket`
This feature is available for GDK CLI v1.1.0 and later.
## Changelog
The following table describes the changes in each version of the GDK CLI. For more information, see the [GDK CLI Releases page](https://github.com/aws-greengrass/aws-greengrass-gdk-cli/releases) on GitHub.
| **Version** | **Changes** |
| --- | --- |
| 1.6.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.6.1 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.6.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.5.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.4.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.3.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.2.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.2.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.2.1 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.2.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) |
| 1.0.0 | Initial version. |
# Install or update the AWS IoT Greengrass Development Kit Command-Line Interface
The AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) is built on Python, so you can use `pip` to install it on your development computer.
**Tip**
You can also install the GDK CLI in a Python virtual environments such as [venv](https://docs.python.org/3/library/venv.html#module-venv). For more information, see [Virtual Environments and Packages](https://docs.python.org/3/tutorial/venv.html) in the *Python 3 documentation*.
**To install or update the GDK CLI**
1. Run the following command to install the latest version of the GDK CLI from its [GitHub repository](https://github.com/aws-greengrass/aws-greengrass-gdk-cli).
```
python3 -m pip install -U git+https://github.com/aws-greengrass/aws-greengrass-gdk-cli.git@v1.6.2
```
**Note**
To install a specific version of the GDK CLI, replace *versionTag* with the version tag to install. You can view version tags for the GDK CLI in its [GitHub repository](https://github.com/aws-greengrass/aws-greengrass-gdk-cli/tags).
```
python3 -m pip install -U git+https://github.com/aws-greengrass/aws-greengrass-gdk-cli.git@versionTag
```
1. Run the following command to verify that the GDK CLI installed successfully.
```
gdk --help
```
If the `gdk` command isn't found, add its folder to PATH.
+ On Linux devices, add `/home/MyUser/.local/bin` to PATH, and replace *MyUser* with the name of your user.
+ On Windows devices, add `PythonPath\\Scripts` to PATH, and replace *PythonPath* with the path to the Python folder on your device.
You can now use the GDK CLI to create, build, and publish Greengrass components. For more information about how to use the GDK CLI, see [AWS IoT Greengrass Development Kit Command-Line Interface commands](greengrass-development-kit-cli-commands.md).
# AWS IoT Greengrass Development Kit Command-Line Interface commands
The AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) provides a command line interface that you can use to create, build, and publish Greengrass components on your development computer. GDK CLI commands use the following format.
```
gdk [arguments]
```
When you [install the GDK CLI](install-greengrass-development-kit-cli.md), the installer adds `gdk` to the PATH so you can run the GDK CLI from the command line.
You can use the following arguments with any command:
+ Use `-h` or `--help` for information about a GDK CLI command.
+ Use `-v` or `--version` to see what version of GDK CLI is installed.
+ Use `-d` or `--debug` to output verbose logs that you can use to debug the GDK CLI.
This section describes the GDK CLI commands and provides examples for each command. The synopsis for each command shows its arguments and their usage. Optional arguments are shown in square brackets.
**Topics**
+ [component](greengrass-development-kit-cli-component.md)
+ [config](greengrass-development-kit-cli-config.md)
+ [test-e2e](greengrass-development-kit-cli-test.md)
# component
Use the `component` command in the AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) to create, build, and publish custom Greengrass components.
**Topics**
+ [init](#greengrass-development-kit-cli-component-init)
+ [build](#greengrass-development-kit-cli-component-build)
+ [publish](#greengrass-development-kit-cli-component-publish)
+ [list](#greengrass-development-kit-cli-component-list)
## init
Initialize a Greengrass component folder from a component template or community component.
The GDK CLI retrieves community components from the [Greengrass Software Catalog](greengrass-software-catalog.md) and component templates from the [AWS IoT Greengrass Component Templates repository on GitHub](https://github.com/aws-greengrass/aws-greengrass-component-templates).
**Note**
If you use GDK CLI v1.0.0, you must run this command in an empty folder. The GDK CLI downloads the template or community component to the current folder.
If you use GDK CLI v1.1.0 or later, you can specify the `--name` argument to specify the folder where the GDK CLI downloads the template or community component. If you use this argument, specify a folder that doesn't exist. The GDK CLI creates the folder for you. If you don't specify this argument, the GDK CLI uses the current folder, which must be empty.
If the component uses the [zip build system](gdk-cli-configuration-file.md#gdk-cli-configuration-file-build-system), the GDK CLI zips certain files in 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 named `HelloWorld.zip`. In the component recipe, the zip artifact name must match the name of the component folder. 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.
If you initialize a template or community component that uses the zip build system to a folder with a different name than the template or component, you must change the zip artifact name in the component recipe. Update the `Artifacts` and `Lifecycle` definitions such that the zip file name matches the name of the component folder. The following example highlights the zip file name in the `Artifacts` and `Lifecycle` definitions.
```
{
...
"Manifests": [
{
"Platform": {
"os": "all"
},
"Artifacts": [
{
"URI": "s3://BUCKET_NAME/COMPONENT_NAME/COMPONENT_VERSION/HelloWorld.zip",
"Unarchive": "ZIP"
}
],
"Lifecycle": {
"Run": "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}"
}
}
]
}
```
```
---
...
Manifests:
- Platform:
os: all
Artifacts:
- URI: "s3://BUCKET_NAME/COMPONENT_NAME/COMPONENT_VERSION/HelloWorld.zip"
Unarchive: ZIP
Lifecycle:
Run: "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}"
```
**Synopsis**
```
$ gdk component init
[--language]
[--template]
[--repository]
[--name]
```
**Arguments (initialize from component template)**
+ `-l`, `--language` – The programming language to use for the template that you specify.
You must specify either `--repository` or `--language` and `--template`.
+ `-t`, `--template` – The component template to use for a local component project. To view available templates, use the [list](#greengrass-development-kit-cli-component-list) command.
You must specify either `--repository` or `--language` and `--template`.
+ `-n`, `--name` – (Optional) The name of the local folder where the GDK CLI initializes the component. Specify a folder that doesn't exist. The GDK CLI creates the folder for you.
This feature is available for GDK CLI v1.1.0 and later.
**Arguments (initialize from community component)**
+ `-r`, `--repository` – The community component to check out into the local folder. To view available community components, use the [list](#greengrass-development-kit-cli-component-list) command.
You must specify either `--repository` or `--language` and `--template`.
+ `-n`, `--name` – (Optional) The name of the local folder where the GDK CLI initializes the component. Specify a folder that doesn't exist. The GDK CLI creates the folder for you.
This feature is available for GDK CLI v1.1.0 and later.
**Output**
The following example shows the output produced when you run this command to initialize a component folder from the Python Hello World template.
```
$ gdk component init -l python -t HelloWorld
[2021-11-29 12:51:40] INFO - Initializing the project directory with a python component template - 'HelloWorld'.
[2021-11-29 12:51:40] INFO - Fetching the component template 'HelloWorld-python' from Greengrass Software Catalog.
```
The following example shows the output produced when you run this command to initialize a component folder from a community component.
```
$ gdk component init -r aws-greengrass-labs-database-influxdb
[2022-01-24 15:44:33] INFO - Initializing the project directory with a component from repository catalog - 'aws-greengrass-labs-database-influxdb'.
[2022-01-24 15:44:33] INFO - Fetching the component repository 'aws-greengrass-labs-database-influxdb' from Greengrass Software Catalog.
```
## build
Build a component's source into a recipe and artifacts that you can publish to the AWS IoT Greengrass service. The GDK CLI runs the build system that you specify in the [GDK CLI configuration file](gdk-cli-configuration-file.md), `gdk-config.json`. You must run this command in the same folder where the `gdk-config.json` file exists.
When you run this command, the GDK CLI creates a recipe and artifacts in the `greengrass-build` folder in the component folder. The GDK CLI saves the recipe in the `greengrass-build/recipes` folder and saves the artifacts in the `greengrass-build/artifacts/componentName/componentVersion` folder.
If you use GDK CLI v1.1.0 or later, the component recipe can specify artifacts that exist in an S3 bucket but not in the local component build folder. You can use this feature to reduce bandwidth usage when you develop components with large artifacts, such as machine learning models.
After you build a component, you can do one of the following to test it on a Greengrass core device:
+ If you develop on a different device than where you run the AWS IoT Greengrass Core software, you must publish the component to deploy it to a Greengrass core device. Publish the component to the AWS IoT Greengrass service, and deploy it to the Greengrass core device. For more information, see the [publish](#greengrass-development-kit-cli-component-build) command and [Create deployments](create-deployments.md).
+ If you develop on the same device where you run the AWS IoT Greengrass Core software, you can publish the component to the AWS IoT Greengrass service to deploy, or you can create a local deployment to install and run the component. To create a local deployment, use the Greengrass CLI. For more information, see [Greengrass Command Line Interface](gg-cli.md) and [Test AWS IoT Greengrass components with local deployments](test-components.md). When you create the local deployment, specify `greengrass-build/recipes` as the recipes folder and `greengrass-build/artifacts` as the artifacts folder.
**Synopsis**
```
$ gdk component build
```
**Arguments**
None
**Output**
The following example shows the output produced when you run this command.
```
$ gdk component build
[2021-11-29 13:18:49] INFO - Getting project configuration from gdk-config.json
[2021-11-29 13:18:49] INFO - Found component recipe file 'recipe.yaml' in the project directory.
[2021-11-29 13:18:49] INFO - Building the component 'com.example.PythonHelloWorld' with the given project configuration.
[2021-11-29 13:18:49] INFO - Using 'zip' build system to build the component.
[2021-11-29 13:18:49] WARNING - This component is identified as using 'zip' build system. If this is incorrect, please exit and specify custom build command in the 'gdk-config.json'.
[2021-11-29 13:18:49] INFO - Zipping source code files of the component.
[2021-11-29 13:18:49] INFO - Copying over the build artifacts to the greengrass component artifacts build folder.
[2021-11-29 13:18:49] INFO - Updating artifact URIs in the recipe.
[2021-11-29 13:18:49] INFO - Creating component recipe in 'C:\Users\MyUser\Documents\greengrass-components\python\HelloWorld\greengrass-build\recipes'.
```
## publish
Publish this component to the AWS IoT Greengrass service. This command uploads build artifacts to an S3 bucket, updates the artifact URI in the recipe, and creates a new version of component from the recipe. The GDK CLI uses the S3 bucket and AWS Region that you specify in the [GDK CLI configuration file](gdk-cli-configuration-file.md), `gdk-config.json`. You must run this command in the same folder where the `gdk-config.json` file exists.
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 `bucket-region-accountId`, where *bucket* and *region* are the values that you specify in `gdk-config.json`, and *accountId* is your AWS account ID. The GDK CLI creates the bucket if it doesn't exist.
If you use GDK CLI v1.2.0 or later, You can override the AWS Region specified in the GDK CLI configuration file using the `--region` parameter. You can also specify additional options using the `--options` parameter. For a list of available options, see [Greengrass Development Kit CLI configuration file](gdk-cli-configuration-file.md).
When you run this command, the GDK CLI publishes the component with the version that you specify in the recipe. If you specify `NEXT_PATCH`, the GDK CLI uses the next patch version that doesn't already exist. Semantic versions use a *major*.*minor*.*patch* numbering system. For more information, see the [semantic version specification](https://semver.org/).
**Note**
If you use GDK CLI v1.1.0 or later, when you run this command, the GDK CLI checks if the component is built. If the component isn't built, the GDK CLI [builds the component](#greengrass-development-kit-cli-component-build) before it publishes the component.
**Synopsis**
```
$ gdk component publish
[--bucket] [--region] [--options]
```
**Arguments**
+ `-b`, `--bucket` – (Optional) Specify the name of the S3 bucket where the GDK CLI publishes component artifacts.
If you don't specify this argument, the GDK CLI uploads to the S3 bucket whose name is `bucket-region-accountId`, where *bucket* and *region* are the values that you specify in `gdk-config.json`, and *accountId* is your AWS account ID. The GDK CLI creates the bucket if it doesn't exist.
The GDK CLI creates the bucket if it doesn't exist.
This feature is available for GDK CLI v1.1.0 and later.
+ `-r`, `--region` – (Optional) Specify the name of the AWS Region to when the component is created. This argument overrides the Region name in the GDK CLI configuration.
This feature is available for GDK CLI v1.2.0 and later.
+ `-o`, `--options` (Optional) Specify a list of options for publishing a component. The argument must be a valid JSON string or a file path to a JSON file containing the publishing options. This argument overrides the options in the GDK CLI configuration.
This feature is available for GDK CLI v1.2.0 and later.
**Output**
The following example shows the output produced when you run this command.
```
$ gdk component publish
[2021-11-29 13:45:29] INFO - Getting project configuration from gdk-config.json
[2021-11-29 13:45:29] INFO - Found component recipe file 'recipe.yaml' in the project directory.
[2021-11-29 13:45:29] INFO - Found credentials in shared credentials file: ~/.aws/credentials
[2021-11-29 13:45:30] INFO - Publishing the component 'com.example.PythonHelloWorld' with the given project configuration.
[2021-11-29 13:45:30] INFO - No private version of the component 'com.example.PythonHelloWorld' exist in the account. Using '1.0.0' as the next version to create.
[2021-11-29 13:45:30] INFO - Uploading the component built artifacts to s3 bucket.
[2021-11-29 13:45:30] INFO - Uploading component artifacts to S3 bucket: {bucket}. If this is your first time using this bucket, add the 's3:GetObject' permission to each core device's token exchange role to allow it to download the component artifacts. For more information, see https://docs.aws.amazon.com/greengrass/v2/developerguide/device-service-role.html.
[2021-11-29 13:45:30] INFO - Not creating an artifacts bucket as it already exists.
[2021-11-29 13:45:30] INFO - Updating the component recipe com.example.PythonHelloWorld-1.0.0.
[2021-11-29 13:45:30] INFO - Creating a new greengrass component com.example.PythonHelloWorld-1.0.0
[2021-11-29 13:45:30] INFO - Created private version '1.0.0' of the component in the account.'com.example.PythonHelloWorld'.
```
## list
Retrieve the list of available component templates and community components.
The GDK CLI retrieves community components from the [Greengrass Software Catalog](greengrass-software-catalog.md) and component templates from the [AWS IoT Greengrass Component Templates repository on GitHub](https://github.com/aws-greengrass/aws-greengrass-component-templates).
You can pass the output of this command to the [init](#greengrass-development-kit-cli-component-init) command to initialize component repositories from templates and community components.
**Synopsis**
```
$ gdk component list
[--template]
[--repository]
```
**Arguments**
+ `-t`, `--template` – (Optional) Specify this argument to list available component templates. This command outputs the name and language of each template in the format `name-language`. For example, in `HelloWorld-python`, the template name is `HelloWorld` and the language is `python`.
+ `-r`, `--repository` – (Optional) Specify this argument to list available community component repositories.
**Output**
The following example shows the output produced when you run this command.
```
$ gdk component list --template
[2021-11-29 12:29:04] INFO - Listing all the available component templates from Greengrass Software Catalog.
[2021-11-29 12:29:04] INFO - Found '2' component templates to display.
1. HelloWorld-python
2. HelloWorld-java
```
# config
Use the `config` command in the AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) to modify the configuration for the GDK in the configuration file, `gdk-config.json`.
**Topics**
+ [update](#greengrass-development-kit-cli-config-update)
## update
Start an interactive prompt to modify fields within an existing GDK configuration file.
**Synopsis**
```
$ gdk config update
[--component]
```
**Arguments**
+ `-c`, `--component` – To update component-related fields in the `gdk-config.json` file. This argument is required since it is the only option.
**Output**
The following example shows the output produced when you run this command to configure a component.
```
$ gdk config update --component
Current value of the REQUIRED component_name is (default: com.example.PythonHelloWorld):
Current value of the REQUIRED author is (default: author):
Current value of the REQUIRED version is (default: NEXT_PATCH):
Do you want to change the build configurations? (y/n)
Do you want to change the publish configurations? (y/n)
[2023-09-26 10:19:48] INFO - Config file has been updated. Exiting...
```
# test-e2e
Use the `test-e2e` command in the AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) to initialize, build, and run end-to-end test modules in the GDK project.
**Topics**
+ [init](#greengrass-development-kit-cli-test-init)
+ [build](#greengrass-development-kit-cli-test-build)
+ [run](#greengrass-development-kit-cli-test-run)
## init
Initialize an existing GDK CLI project with a testing module that uses Greengrass Testing Framework (GTF).
By default, GDK CLI retrieves the maven module template from the [AWS IoT Greengrass Component Templates repository on GitHub](https://github.com/aws-greengrass/aws-greengrass-component-templates). This maven module comes with a dependency on the `aws-greengrass-testing-standalone` JAR file.
This command creates a new directory called `gg-e2e-tests` inside of the GDK project. If the testing module directory already exists and is not empty, the command exits without doing anything. This `gg-e2e-tests` folder contains the Cucumber feature and step definitions structured in a maven project.
By default, this command will try to use the latest release version of GTF.
**Synopsis**
```
$ gdk test-e2e init
[--gtf-version]
```
**Arguments**
+ `-ov`, `--gtf-version` – (Optional) The version of the GTF to use with the end-to-end testing module in the GDK project. This value must be one of the GTF versions from [ releases](https://github.com/aws-greengrass/aws-greengrass-testing/releases). This argument overrides the `gtf_version` in the GDK CLI configuration.
**Output**
The following example shows the output produced when you run this command to initialize the GDK project with the testing module.
```
$ gdk test-e2e init
[2023-12-06 12:20:28] INFO - Using the GTF version provided in the GDK test config 1.2.0
[2023-12-06 12:20:28] INFO - Downloading the E2E testing template from GitHub into gg-e2e-tests directory...
```
## build
**Note**
You must build the component by running **gdk component build** before building the end-to-end test module.
Build the end-to-end testing module. The GDK CLI builds the testing module using the build system that you specify in the [GDK CLI configuration file](gdk-cli-configuration-file.md), `gdk-config.json`, under the `test-e2e` property. You must run this command in the same folder where the `gdk-config.json` file exists.
By default, GDK CLI uses maven build system to build the testing module. [Maven](https://maven.apache.org/) is required to run the `gdk test-e2e build` command.
You must build the component by running **gdk-component-build** before building the testing module, if the test feature files have variables like `GDK_COMPONENT_NAME` and `GDK_COMPONENT_RECIPE_FILE` to interpolate.
When you run this command, the GDK CLI interpolates all of the variables from the GDK project configuration and builds the `gg-e2e-tests` module to generate the final testing JAR file.
**Synopsis**
```
$ gdk test-e2e build
```
**Arguments**
None
**Output**
The following example shows the output produced when you run this command.
```
$ gdk test-e2e build
[2023-07-20 15:36:48] INFO - Updating feature file: file:///path/to//HelloWorld/greengrass-build/gg-e2e-tests/src/main/resources/greengrass/features/component.feature
[2023-07-20 15:36:48] INFO - Creating the E2E testing recipe file:///path/to/HelloWorld/greengrass-build/recipes/e2e_test_recipe.yaml
[2023-07-20 15:36:48] INFO - Building the E2E testing module
[2023-07-20 15:36:48] INFO - Running the build command 'mvn package'
.........
```
## run
Run the testing module with the testing options in the GDK configuration file.
**Note**
You must build the testing module by running **gdk test-e2e build** before running the end-to-end tests.
**Synopsis**
```
$ gdk test-e2e run
[--gtf-options]
```
**Arguments**
+ `-oo`, `--gtf-options` – (Optional) Specify a list of options for running the end-to-end tests. The argument must be a valid JSON string or a file path to a JSON file containing the GTF options. The options provided in the configuration file are merged with the ones provided in the command arguments. If an option is present in both places, the one in argument takes precendence over the one from the configuration file.
If the `tags` option is not specified in this command, GDK uses `Sample` for tags. If `ggc-archive` is not specified, GDK downloads the latest version of the Greengrass nucleus archive.
**Output**
The following example shows the output produced when you run this command.
```
$ gdk test-e2e run
[2023-07-20 16:35:53] INFO - Downloading latest nucleus archive from url https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-latest.zip
[2023-07-20 16:35:57] INFO - Running test jar with command java -jar /path/to/greengrass-build/gg-e2e-tests/target/uat-features-1.0.0.jar —ggc-archive=/path/to/aws-greengrass-gdk-cli/HelloWorld/greengrass-build/greengrass-nucleus-latest.zip —tags=Sample
16:35:59.693 [] [] [] [INFO] com.aws.greengrass.testing.modules.GreengrassContextModule - Extracting /path/to/workplace/aws-greengrass-gdk-cli/HelloWorld/greengrass-build/greengrass-nucleus-latest.zip into /var/folders/7g/ltzcb_3s77nbtmkzfb6brwv40000gr/T/gg-testing-7718418114158172636/greengrass
16:36:00.534 [gtf-1.1.0-SNAPSHOT] [] [] [INFO] com.aws.greengrass.testing.features.LoggerSteps - GTF Version is gtf-1.1.0-SNAPSHOT
.......
```
# Greengrass Development Kit CLI configuration file
The AWS 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](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-init) to initialize component repositories with this configuration file.
**Topics**
+ [GDK CLI configuration file format](#gdk-config-format)
+ [GDK CLI configuration file examples](#gdk-config-examples)
## 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. This value must be one of the GDK CLI versions from [ releases](https://github.com/aws-greengrass/aws-greengrass-gdk-cli/releases).
`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 AWS 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 version `1.0.0`.
If you choose this option, you can't use the [Greengrass CLI](greengrass-cli-component.md) to locally deploy and test the component to your local development computer that runs the AWS 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](https://semver.org/).
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](greengrass-cli-component.md).
`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 named `HelloWorld.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` or `recipe.yaml`)
+ Build folders, such as `greengrass-build`
+ `maven` – Runs the `mvn clean package` command to build the component's source into artifacts. Choose this option for components that use [Maven](https://maven.apache.org/), such as Java components.
On Windows devices, this feature is available for GDK CLI v1.1.0 and later.
+ `gradle` – Runs the `gradle build` command to build the component's source into artifacts. Choose this option for components that use [Gradle](https://gradle.org/). 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 the `gradlew` command to build the component's source into artifacts. Choose this option for components that use the [Gradle Wrapper ](https://docs.gradle.org/current/userguide/gradle_wrapper.html).
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 the `custom_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` for `build_system`.
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](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-build).
+ Recipe folder: `greengrass-build/recipes`
+ Artifacts folder: `greengrass-build/artifacts/componentName/componentVersion`
Replace *componentName* with the component name, and replace *componentVersion* with the component version or `NEXT_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\$1\$1 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](https://github.com/awslabs/aws-greengrass-labs-local-web-server).
`options`
(Optional) Additional configuration options used during the component build process.
This feature is available for GDK CLI v1.2.0 and later.
`excludes`
A list of glob patterns that define which files to exclude from the component directory when building the zip file. Only valid when the `build_system` is `zip`.
In GDK CLI versions 1.4.0 and earlier, any file that matches an entry in the excludes list is excluded from all of the component's subdirectories. To achieve the same behavior in GDK CLI versions 1.5.0 and later, prepend `**/` to the existing entries in the excludes list. For example, `*.txt` will exclude text files from just the directory; `**/*.txt` will exclude text files from all directories and subdirectories.
In GDK CLI versions 1.5.0 and later, you may see a warning during the component build when `excludes` is defined in the GDK configuration file. To disable this warning, set the environment variable `GDK_EXCLUDES_WARN_IGNORE` to `true`.
The GDK CLI always excludes the following files from the zip file:
+ The `gdk-config.json` file
+ The recipe file (`recipe.json` or `recipe.yaml`)
+ Build folders, such as `greengrass-build`
The following files are excluded by default. However, you can control which of these files are excluded with the `excludes` option.
+ Any folder that starts with the prefix "test" (`test*`)
+ All hidden files
+ The `node_modules` folder
If you specify the `excludes` option, the GDK CLI excludes only those files you set with the `excludes` option. If you don't specify the `excludes` option, the GDK CLI excludes the previously noted default files and folders.
`zip_name`
The zip file name to use when you create a zip artifact during the build process. Only valid when the `build_system` is `zip`. If the `build_system` is empty, the component name is used for the zip file name.
`publish`
The configuration to use to publish this component to the AWS 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 `bucket-region-accountId`, where *bucket* and *region* are the values that you specify in `gdk-config.json`, and *accountId* is your AWS 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 AWS Region where the GDK CLI publishes this component.
This property is optional if you are using GDK CLI v1.3.0 or later.
`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 [https://boto3.amazonaws.com/v1/documentation/api/latest/reference/customizations/s3.html#boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/customizations/s3.html#boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS) class in the *Boto3 documentation.*.
`test-e2e`
(Optional) The configuration to use during end-to-end testing of the component. This feature is available for GDK CLI v1.3.0 and later.
`build`
`build_system` – The build system to use. Default option is `maven`. Choose from the following options:
+ `maven` – Runs the `mvn package` command to build the testing module. Choose this option for building the testing module that uses [Maven](https://maven.apache.org/).
+ `gradle` – Runs the `gradle build` command to build the testing module. Choose this option for the testing module that uses [Gradle](https://gradle.org/).
`gtf_version`
(Optional) The version of the Greengrass Testing Framework (GTF) to use as a dependency of the end-to-end testing module when you initialize the GDK project with GTF. This value must be one of the GTF versions from [ releases](https://github.com/aws-greengrass/aws-greengrass-testing/releases). The default is GTF version 1.1.0.
`gtf_options`
(Optional) Additional configuration options used during the end-to-end testing of the component.
The following list includes the options you can use with GTF version 1.1.0.
+ `additional-plugins` – (Optional) Additional Cucumber plugins
+ `aws-region` – Targets specific regional endpoints for AWS services. Defaults to what the AWS SDK discovers.
+ `credentials-path` – Optional AWS profile credentials path. Defaults to credentials discovered on host environment.
+ `credentials-path-rotation` – Optional rotation duration for AWS credentials. Defaults to 15 minutes or `PT15M`.
+ `csr-path` – The path for the CSR using which the device certificate will be generated.
+ `device-mode` – The target device under test. Defaults to local device.
+ `env-stage` – Targets the deployment environment of Greengrass. Defaults to production.
+ `existing-device-cert-arn` – The arn of an existing certificate that you want to use as a device certificate for Greengrass.
+ `feature-path` – File or directory containing additional feature files. Default is no additional feature files are used.
+ `gg-cli-version` – Overrides the version of the Greengrass CLI. Defaults to the value found in `ggc.version`.
+ `gg-component-bucket` – The name of an existing Amazon S3 bucket that houses Greengrass components.
+ `gg-component-overrides` – A list of Greengrass component overrides.
+ `gg-persist` – A list of test elements to persist after a test run. Default behavior is to persist nothing. Accepted values are: `aws.resources`, `installed.software`, and `generated.files`.
+ `gg-runtime` – A list of values to influence how the test interacts with testing resources. These values supersede the `gg.persist` parameter. If the default is empty, it assumes all testing resources are manged by test case, including the installed Greengrass runtime. Accepted values are: `aws.resources`, `installed.software`, and `generated.files`.
+ `ggc-archive` – The path to the archived Greengrass nucleus component.
+ `ggc-install-root` – Directory to install the Greengrass nucleus component. Defaults to test.temp.path and test run folder.
+ `ggc-log-level` – Set the Greengrass nucleus log level for the test run. Default is "INFO".
+ `ggc-tes-rolename` – The IAM role that AWS IoT Greengrass Core will assume to access AWS services. If a role with given name does not exist then one will be created and default access policy.
+ `ggc-trusted-plugins` – The comma separate list of the paths (on host) of the trusted plugins that need to added to Greengrass. To provide the path on the DUT itself, prefix the path with 'dut:'
+ `ggc-user-name` – The user:group posixUser value for the Greengrass nucleus. Defaults to the current username that is logged in.
+ `ggc-version` – Overrides the version of the running Greengrass nucleus component. Defaults to the value found in ggc.archive.
+ `log-level` – Log level of the test run. Defaults to "INFO".
+ `parallel-config` – Set of batch index and number of batches as a JSON String. Default value of batch index is 0 and number of batches is 1.
+ `proxy-url` – Configure all tests to route traffic through this URL.
+ `tags` – Only run feature tags. Can be intersected with '&'
+ `test-id-prefix` – A common prefix applied to all test specific resources including AWS resource names and tags. Default is a "gg" prefix.
+ `test-log-path` – Directory that will contain the results of the entire test run. Defaults to "testResults".
+ `test-results-json` – Flag to determine if a resulting Cucumber JSON report is generated written to disk. Defaults to true.
+ `test-results-log` – Flag to determine if the console output is generated written to disk. Defaults to false.
+ `test-results-xml` – Flag to determine if a resulting JUnit XML report is generated written to disk. Defaults to true.
+ `test-temp-path` – Directory to generate local test artifacts. Defaults to a random temp directory prefixed with gg-testing.
+ `timeout-multiplier` – Multiplier provided to all test timeouts. Default is 1.0.
## 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"
}
}
}
}
},
"test-e2e":{
"build":{
"build_system": "maven"
},
"gtf_version": "1.1.0",
"gtf_options": {
"tags": "Sample"
}
},
"gdk_version": "1.6.1"
}
}
```
### 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"
}
}
}
}
},
"test-e2e":{
"build":{
"build_system": "maven"
},
"gtf_version": "1.1.0",
"gtf_options": {
"tags": "Sample"
}
},
"gdk_version": "1.6.1"
}
}
```
### Community components
Several community components in the [Greengrass Software Catalog](greengrass-software-catalog.md) use the GDK CLI. You can explore the GDK CLI configuration files in these components' repositories.
**To view community components' GDK CLI configuration files**
1. 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
```
1. 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
```
# Greengrass Command Line Interface
The Greengrass Command Line Interface (CLI) lets you interact with AWS IoT Greengrass Core on your device to locally develop components and debug issues. For example, you can use the Greengrass CLI to create a local deployment and restart a component on the core device.
Deploy the [Greengrass CLI component](greengrass-cli-component.md) (`aws.greengrass.Cli`) to install the Greengrass CLI on your core device.
**Important**
We recommend that you use this component in only development environments, not production environments. This component provides access to information and operations that you typically won't need in a production environment. Follow the principle of least privilege by deploying this component to only core devices where you need it.
**Topics**
+ [Install the Greengrass CLI](install-gg-cli.md)
+ [Greengrass CLI commands](gg-cli-reference.md)
# Install the Greengrass CLI
You can install the Greengrass CLI in one of the following ways:
+ Use the `--deploy-dev-tools` argument when you first set up AWS IoT Greengrass Core software on your device. You must also specify `--provision true` to apply this argument.
+ Deploy the Greengrass CLI component (`aws.greengrass.Cli`) on your device.
This section describes the steps to deploy the Greengrass CLI component. For information about installing the Greengrass CLI during initial setup, see [Tutorial: Getting started with AWS IoT Greengrass V2](getting-started.md).
## Prerequisites
To deploy the Greengrass CLI component, you must meet the following requirements:
+ AWS IoT Greengrass Core software installed and configured on your core device. For more information, see [Tutorial: Getting started with AWS IoT Greengrass V2](getting-started.md).
+ To use the AWS CLI to deploy the Greengrass CLI, you must have installed and configured the AWS CLI. For more information, see [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) in the *AWS Command Line Interface User Guide*.
+ You must be authorized to use the Greengrass CLI to interact with the AWS IoT Greengrass Core software. Do one of the following to use the Greengrass CLI:
+ Use the system user that runs the AWS IoT Greengrass Core software.
+ Use a user with root or adminstrative permissions. On Linux core devices, you can use `sudo` to gain root permissions.
+ Use a system user that's in a group that you specify in the `AuthorizedPosixGroups` or `AuthorizedWindowsGroups` configuration parameters when you deploy the component. For more information, see [Greengrass CLI component configuration](greengrass-cli-component.md#greengrass-cli-component-configuration).
## Deploy the Greengrass CLI component
Complete the following steps to deploy the Greengrass CLI component to your core device:
### To deploy the Greengrass CLI component (console)
1. Sign in to the [AWS IoT Greengrass console](https://console.aws.amazon.com/greengrass).
1. In the navigation menu, choose **Components**.
1. On the **Components** page, on the **Public components** tab, choose `aws.greengrass.Cli`.
1. On the **aws.greengrass.Cli** page, choose **Deploy**.
1. From **Add to deployment**, choose **Create new deployment**.
1. On the **Specify target** page, under **Deployment targets**, in the **Target name** list, choose the Greengrass group that you want to deploy to, and choose **Next**.
1. On the **Select components** page, verify that the **aws.greengrass.Cli** component is selected, and choose **Next**.
1. On the **Configure components** page, keep the default configuration settings, and choose **Next**.
1. On the **Configure advanced setting** page, keep the default configuration settings, and choose **Next**.
1. On the **Review** page, click **Deploy**
### To deploy the Greengrass CLI component (AWS CLI)
1. On your device, create a `deployment.json` file to define the deployment configuration for the Greengrass CLI component. This file should look like the following:
```
{
"targetArn":"targetArn",
"components": {
"aws.greengrass.Cli": {
"componentVersion": "2.17.0",
"configurationUpdate": {
"merge": "{\"AuthorizedPosixGroups\":\",,...,\",\"AuthorizedWindowsGroups\":\",,...,\"}"
}
}
}
}
```
+ In the `target` field, replace `targetArn` with the Amazon Resource Name (ARN) of the thing or thing group to target for the deployment, in the following format:
+ Thing: `arn:aws:iot:region:account-id:thing/thingName`
+ Thing group: `arn:aws:iot:region:account-id:thinggroup/thingGroupName`
+ In the `aws.greengrass.Cli` component object, specify values as follows:
`version`
The version of the Greengrass CLI component.
`configurationUpdate.AuthorizedPosixGroups`
(Optional) A string that contains a comma-separated list of system groups. You authorize these system groups to use the Greengrass CLI to interact with the AWS IoT Greengrass Core software. You can specify group names or group IDs. For example, `group1,1002,group3` authorizes three system groups (`group1`, `1002`, and `group3`) to use the Greengrass CLI.
If you don't specify any groups to authorize, you can use the Greengrass CLI as the root user (`sudo`) or as the system user that runs the AWS IoT Greengrass Core software.
`configurationUpdate.AuthorizedWindowsGroups`
(Optional) A string that contains a comma-separated list of system groups. You authorize these system groups to use the Greengrass CLI to interact with the AWS IoT Greengrass Core software. You can specify group names or group IDs. For example, `group1,1002,group3` authorizes three system groups (`group1`, `1002`, and `group3`) to use the Greengrass CLI.
If you don't specify any groups to authorize, you can use the Greengrass CLI as an administrator or as the system user that runs the AWS IoT Greengrass Core software.
1. Run the following command to deploy the Greengrass CLI component on the device:
```
$ aws greengrassv2 create-deployment --cli-input-json file://path/to/deployment.json
```
During installation, the component adds a symbolic link to `greengrass-cli` in the `/greengrass/v2/bin` folder on your device, and you run the Greengrass CLI from this path. To run the Greengrass CLI without its absolute path, add your `/greengrass/v2/bin` folder to your PATH variable. To verify the Greengrass CLI installation, run the following command:
------
#### [ Linux or Unix ]
```
/greengrass/v2/bin/greengrass-cli help
```
------
#### [ Windows ]
```
C:\greengrass\v2\bin\greengrass-cli help
```
------
You should see the following output:
```
Usage: greengrass-cli [-hV] [--ggcRootPath=] [COMMAND]
Greengrass command line interface
--ggcRootPath=
The AWS IoT Greengrass V2 root directory.
-h, --help Show this help message and exit.
-V, --version Print version information and exit.
Commands:
help Show help information for a command.
component Retrieve component information and stop or restart
components.
deployment Create local deployments and retrieve deployment status.
logs Analyze Greengrass logs.
get-debug-password Generate a password for use with the HTTP debug view
component.
```
If the `greengrass-cli` isn't found, the deployment might have failed to install the Greengrass CLI. For more information, see [Troubleshooting AWS IoT Greengrass V2](troubleshooting.md).
# Greengrass CLI commands
The Greengrass CLI provides a command line interface to interact locally with your AWS IoT Greengrass core device. Greengrass CLI commands use the following format.
```
$ greengrass-cli [arguments]
```
By default, the `greengrass-cli` executable file in the `/greengrass/v2/bin/` folder interacts with the version of the AWS IoT Greengrass Core software running in the `/greengrass/v2` folder. If you call an executable that is not placed in this location, or if you want to interact with AWS IoT Greengrass Core software in a different location, then you must use one of the following methods to explicitly specify the root path of the AWS IoT Greengrass Core software that you want to interact with:
+ Set the `GGC_ROOT_PATH` environment variable to `/greengrass/v2`.
+ Add the `--ggcRootPath /greengrass/v2` argument to your command as shown in the following example.
```
greengrass-cli --ggcRootPath /greengrass/v2 [arguments]
```
You can use the following arguments with any command:
+ Use `--help` for information about a specific Greengrass CLI command.
+ Use `--version` for information about the Greengrass CLI version.
This section describes the Greengrass CLI commands and provides examples for these commands. The synopsis for each command shows its arguments and their usage. Optional arguments are shown in square brackets.
**Topics**
+ [component](gg-cli-component.md)
+ [deployment](gg-cli-deployment.md)
+ [logs](gg-cli-logs.md)
+ [get-debug-password](gg-cli-get-debug-password.md)
# component
Use the `component` command to interact with local components on your core device.
**Subcommands**
+ [details](#component-details)
+ [list](#component-list)
+ [restart](#component-restart)
+ [stop](#component-stop)
## details
Retrieve the version, status, and configuration of one component.
**Synopsis**
```
greengrass-cli component details --name
```
**Arguments**
`--name`, `-n`. The component name.
**Output**
The following example shows the output produced when you run this command.
```
$ sudo greengrass-cli component details --name MyComponent
Component Name: MyComponent
Version: 1.0.0
State: RUNNING
Configuration: null
```
## list
Retrieve the name, version, status, and configuration of each component installed on the device.
**Synopsis**
```
greengrass-cli component list
```
**Arguments**
None
**Output**
The following example shows the output produced when you run this command.
```
$ sudo greengrass-cli component list
Components currently running in Greengrass:
Component Name: FleetStatusService
Version: 0.0.0
State: RUNNING
Configuration: {"periodicUpdateIntervalSec":86400.0}
Component Name: UpdateSystemPolicyService
Version: 0.0.0
State: RUNNING
Configuration: null
Component Name: aws.greengrass.Nucleus
Version: 2.0.0
State: FINISHED
Configuration: {"awsRegion":"region","runWithDefault":{"posixUser":"ggc_user:ggc_group"},"telemetry":{}}
Component Name: DeploymentService
Version: 0.0.0
State: RUNNING
Configuration: null
Component Name: TelemetryAgent
Version: 0.0.0
State: RUNNING
Configuration: null
Component Name: aws.greengrass.Cli
Version: 2.0.0
State: RUNNING
Configuration: {"AuthorizedPosixGroups":"ggc_user"}
```
## restart
Restart components.
**Synopsis**
```
greengrass-cli component restart --names ,...
```
**Arguments**
`--names`, `-n`. The component name. At least one component name is required. You can specify additional component names, separating each name with a comma.
**Output**
None
## stop
Stop running components.
**Synopsis**
```
greengrass-cli component stop --names ,...
```
**Arguments**
`--names`, `-n`. The component name. At least one component name is required. You can specify additional component names if needed, separating each name with a comma.
**Output**
None
# deployment
Use the `deployment` command to interact with local components on your core device.
To monitor the progress of a local deployment, use the `status` subcommand. You can't monitor the progress of a local deployment using the console.
**Subcommands**
+ [create](#deployment-create)
+ [cancel](#deployment-cancel)
+ [list](#deployment-list)
+ [status](#deployment-status)
## create
Create or update a local deployment using specified component recipes, artifacts, and runtime arguments.
**Synopsis**
```
greengrass-cli deployment create
--recipeDir path/to/component/recipe
[--artifactDir path/to/artifact/folder ]
[--update-config {component-configuration}]
[--groupId ]
[--merge "="]...
[--runWith ":posixUser=[:]"]...
[--systemLimits "{component-system-resource-limits}]"]...
[--remove ,...]
[--failure-handling-policy ]
```
**Arguments**
+ `--recipeDir`, `-r`. The full path to the folder that contains the component recipe files.
+ `--artifactDir`, `-a`. The full path to the folder that contains the artifact files you want to include in your deployment. The artifacts folder must contain the following directory structure:
```
/path/to/artifact/folder///
```
+ `--update-config`, `-c`. The configuration arguments for the deployment, provided as a JSON string or a JSON file. The JSON string should be in the following format:
```
{ \
"componentName": { \
"MERGE": {"config-key": "config-value"}, \
"RESET": ["path/to/reset/"] \
} \
}
```
`MERGE` and `RESET` are case-sensitive and must be in upper case.
+ `--groupId`, `-g`. The target thing group for the deployment.
+ `--merge`, `-m`. The name and version of the target component that you want to add or update. You must provide the component information in the format `=`. Use a separate argument for each additional component to specify. If needed, use the `--runWith` argument to provide the `posixUser`, `posixGroup`, and `windowsUser` information for running the component.
+ `--runWith`. The `posixUser`, `posixGroup`, and `windowsUser` information for running a generic or Lambda component. You must provide this information in the format `:{posixUser|windowsUser}=[:<=posixGroup>]`. For example, you might specify **HelloWorld:posixUser=ggc\$1user:ggc\$1group** or **HelloWorld:windowsUser=ggc\$1user**. Use a separate argument for each additional option to specify.
For more information, see [Configure the user that runs components](configure-greengrass-core-v2.md#configure-component-user).
+ `--systemLimits`. The system resource limits to apply to generic and non-containerized Lambda components' processes on the core device. You can configure the maximum amount of CPU and RAM usage that each component's processes can use. Specify a serialized JSON object or a file path to a JSON file. The JSON object must have the following format.
```
{ \
"componentName": { \
"cpus": cpuTimeLimit, \
"memory": memoryLimitInKb \
} \
}
```
You can configure the following system resource limits for each component:
+ `cpus` – The maximum amount of CPU time that this component's processes can use on the core device. A core device's total CPU time is equivalent to the device's number of CPU cores. For example, on a core device with 4 CPU cores, you can set this value to `2` to limit this component's processes to 50 percent usage of each CPU core. On a device with 1 CPU core, you can set this value to `0.25` to limit this component's processes to 25 percent usage of the CPU. If you set this value to a number greater than the number of CPU cores, the AWS IoT Greengrass Core software doesn't limit the component's CPU usage.
+ `memory` – The maximum amount of RAM (in kilobytes) that this component's processes can use on the core device.
For more information, see [Configure system resource limits for components](configure-greengrass-core-v2.md#configure-component-system-resource-limits).
This feature is available for v2.4.0 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md) and Greengrass CLI on Linux core devices. AWS IoT Greengrass doesn't currently support this feature on Windows core devices.
+ `--remove`. The name of the target component that you want to remove from a local deployment. If the component defines an [uninstall lifecycle](component-recipe-reference.md#uninstall-lifecycle-definition) step, the AWS IoT Greengrass Core software runs the uninstall script before removing the component. To remove a component that was merged from a cloud deployment, you must provide the group ID of the target thing group in the following format:
------
#### [ Greengrass nucleus v2.4.0 and later ]
```
--remove --groupId
```
------
#### [ Earlier than v2.4.0 ]
```
--remove --groupId thinggroup/
```
------
+ `--failure-handling-policy`. Defines the action taken when a deployment fails. There are two actions that you can specify:
+ `ROLLBACK` –
+ `DO_NOTHING` –
This feature is available for v2.11.0 and later of the [Greengrass nucleus](greengrass-nucleus-component.md).
**Output**
The following example shows the output produced when you run this command.
```
$ sudo greengrass-cli deployment create \
--merge MyApp1=1.0.0 \
--merge MyApp2=1.0.0 --runWith MyApp2:posixUser=ggc_user \
--remove MyApp3 \
--recipeDir recipes/ \
--artifactDir artifacts/
Local deployment has been submitted! Deployment Id: 44d89f46-1a29-4044-ad89-5151213dfcbc
```
## cancel
Cancels the specified deployment.
Synopsis
```
greengrass-cli deployment cancel
-i
```
Arguments
`-i`. The unique identifier of the deployment to cancel. The deployment ID is returned in the output of the `create` command.
Output
+ None
## list
Retrieve the status of the last 10 local deployments.
**Synopsis**
```
greengrass-cli deployment list
```
**Arguments**
None
**Output**
The following example shows the output produced when you run this command. Depending on the status of your deployment, the output shows one of the following status values: `IN_PROGRESS`, `SUCCEEDED`, or `FAILED`.
```
$ sudo greengrass-cli deployment list
44d89f46-1a29-4044-ad89-5151213dfcbc: SUCCEEDED
Created on: 6/27/23 11:05 AM
```
## status
Retrieve the status of a specific deployment.
**Synopsis**
```
greengrass-cli deployment status -i
```
**Arguments**
`-i`. The ID of the deployment.
**Output**
The following example shows the output produced when you run this command. Depending on the status of your deployment, the output shows one of the following status values: `IN_PROGRESS`, `SUCCEEDED`, or `FAILED`.
```
$ sudo greengrass-cli deployment status -i 44d89f46-1a29-4044-ad89-5151213dfcbc
44d89f46-1a29-4044-ad89-5151213dfcbc: FAILED
Created on: 6/27/23 11:05 AM
Detailed Status:
Deployment Error Stack: List of error codes
Deployment Error Types: List of error types
Failure Cause: Cause
```
# logs
Use the `logs` command to analyze Greengrass logs on your core device.
**Subcommands**
+ [get](#logs-get)
+ [list-keywords](#logs-list-keywords)
+ [list-log-files](#logs-list-log-files)
## get
Collect, filter, and visualize Greengrass log files. This command supports only JSON-formatted log files. You can specify the [logging format](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-logging-format) in the nucleus configuration.
**Synopsis**
```
greengrass-cli logs get
[--log-dir path/to/a/log/folder]
[--log-file path/to/a/log/file]
[--follow true | false ]
[--filter ]
[--time-window , ]
[--verbose ]
[--no-color ]
[--before ]
[--after ]
[--syslog ]
[--max-long-queue-size ]
```
**Arguments**
+ `--log-dir`, `-ld`. The path to the directory to check for log files, such as **`/greengrass/v2`/logs**. Do not use with `--syslog`. Use a separate argument for each additional directory to specify. You must use at least one of `--log-dir` or `--log-file`. You can also use both arguments in a single command.
+ `--log-file`, `-lf`. The paths to the log directories you want to use. Use a separate argument for each additional directory to specify. You must use at least one of `--log-dir` or `--log-file`. You can also use both arguments in a single command.
+ `--follow`, `-fol`. Show log updates as they occur. Greengrass CLI continues to run and reads from the specified logs. If you specify a time window, then Greengrass CLI stops monitoring logs after all of the time windows end.
+ `--filter`, `-f`. The keyword, regular expressions, or key-value pair to use as a filter. Provide this value as a string, a regular expression, or as a key-value pair. Use a separate argument for each additional filter to specify.
When evaluated, multiple filters specified in a single argument are separated by OR operators, and filters specified in additional arguments are combined with AND operators. For example, if your command includes `--filter "installed" --filter "name=alpha,name=beta"`, then Greengrass CLI will filter and display log messages that contain both the keyword `installed` and a `name` key that has the values `alpha` or `beta`.
+ `--time-window`, `-t`. The time window for which to show log information. You can use both exact timestamps and relative offsets. You must provide this information in the format `,`. If you do not specify either the begin time or the end time, then the value for that option defaults to the current system date and time. Use a separate argument for each additional time window to specify.
Greengrass CLI supports the following formats for timestamps:
+ `yyyy-MM-DD`, for example, `2020-06-30`. The time defaults to 00:00:00 when you use this format.
`yyyyMMDD`, for example, `20200630`. The time defaults to 00:00:00 when you use this format.
`HH:mm:ss`, for example, `15:30:45`. The date defaults to the current system date when you use this format.
`HH:mm:ssSSS`, for example, `15:30:45`. The date defaults the current system date when you use this format.
`YYYY-MM-DD'T'HH:mm:ss'Z'`, for example, `2020-06-30T15:30:45Z`.
`YYYY-MM-DD'T'HH:mm:ss`, for example, `2020-06-30T15:30:45`.
`yyyy-MM-dd'T'HH:mm:ss.SSS`, for example, `2020-06-30T15:30:45.250`.
Relative offsets specify a time period offset from the current system time. Greengrass CLI supports the following format for relative offsets: `+|-[h|hr|hours][valuem|min|minutes][value]s|sec|seconds`.
For example, the following argument to specify a time window between 1 hour and 2 hours 15 minutes before the current time is `--time-window -2h15min,-1hr`.
+ `--verbose`. Show all fields from the log messages. Do not use with `--syslog`.
+ `--no-color`, `-nc`. Remove color coding. The default color coding for log messages uses bold red text. Supports only UNIX-like terminals because it uses ANSI escape sequences.
+ `--before`, `-b`. The number of lines to show preceding a matched log entry. Default is 0.
+ `--after`, `-a`. The number of lines to show following a matched log entry. Default is 0.
+ `--syslog`. Process all log files using the syslog protocol defined by RFC3164. Do not use with `--log-dir` and `--verbose`. The syslog protocol uses the following format: `"<$Priority>$Timestamp $Host $Logger ($Class): $Message"`. If you do not specify a log file, then Greengrass CLI reads log messages from the following locations: `/var/log/messages`, `/var/log/syslog`, or the `/var/log/system.log`.
AWS IoT Greengrass doesn't currently support this feature on Windows core devices.
+ `--max-log-queue-size`, `-m`. The maximum number of log entries to allocate to memory. Use this option to optimize memory usage. Default is 100.
**Output**
The following example shows the output produced when you run this command.
```
$ sudo greengrass-cli logs get --verbose \
--log-file /greengrass/v2/logs/greengrass.log \
--filter deployment,serviceName=DeploymentService \
--filter level=INFO \
--time-window 2020-12-08T01:11:17,2020-12-08T01:11:22
2020-12-08T01:11:17.615Z [INFO] (pool-2-thread-14) com.aws.greengrass.deployment.DeploymentService: Current deployment finished. {DeploymentId=44d89f46-1a29-4044-ad89-5151213dfcbc, serviceName=DeploymentService, currentState=RUNNING}
2020-12-08T01:11:17.675Z [INFO] (pool-2-thread-14) com.aws.greengrass.deployment.IotJobsHelper: Updating status of persisted deployment. {Status=SUCCEEDED, StatusDetails={detailed-deployment-status=SUCCESSFUL}, ThingName=MyThing, JobId=22d89f46-1a29-4044-ad89-5151213dfcbc
```
## list-keywords
Show suggested keywords that you can use to filter log files.
**Synopsis**
```
greengrass-cli logs list-keywords [arguments]
```
**Arguments**
None
**Output**
The following examples show the output produced when you run this command.
```
$ sudo greengrass-cli logs list-keywords
Here is a list of suggested keywords for Greengrass log:
level=$str
thread=$str
loggerName=$str
eventType=$str
serviceName=$str
error=$str
```
```
$ sudo greengrass-cli logs list-keywords --syslog
Here is a list of suggested keywords for syslog:
priority=$int
host=$str
logger=$str
class=$str
```
## list-log-files
Show log files located in a specified directory.
**Synopsis**
```
greengrass-cli logs list-log-files [arguments]
```
**Arguments**
`--log-dir`, `-ld`. The path to the directory to check for log files.
**Output**
The following example shows the output produced when you run this command.
```
$ sudo greengrass-cli logs list-log-files -ld /greengrass/v2/logs/
/greengrass/v2/logs/aws.greengrass.Nucleus.log
/greengrass/v2/logs/main.log
/greengrass/v2/logs/greengrass.log
Total 3 files found.
```
# get-debug-password
Use the `get-debug-password` command to print a randomly generated password for the [local debug console component](local-debug-console-component.md) (`aws.greengrass.LocalDebugConsole`). The password expires 8 hours after it is generated.
**Synopsis**
```
greengrass-cli get-debug-password
```
**Arguments**
None
**Output**
The following example shows the output produced when you run this command.
```
$ sudo greengrass-cli get-debug-password
Username: debug
Password: bEDp3MOHdj8ou2w5de_sCBI2XAaguy3a8XxREXAMPLE
Password expires at: 2021-04-01T17:01:43.921999931-07:00
The local debug console is configured to use TLS security. The certificate is self-signed so you will need to bypass your web browser's security warnings to open the console.
Before you bypass the security warning, verify that the certificate fingerprint matches the following fingerprints.
SHA-256: 15 0B 2C E2 54 8B 22 DE 08 46 54 8A B1 2B 25 DE FB 02 7D 01 4E 4A 56 67 96 DA A6 CC B1 D2 C4 1B
SHA-1: BC 3E 16 04 D3 80 70 DA E0 47 25 F9 90 FA D6 02 80 3E B5 C1
```
# Use AWS IoT Greengrass Testing Framework
Greengrass Testing Framework (GTF) is a collection of building blocks that supports end-to-end automation from the customer perspective. GTF uses [Cucumber](https://cucumber.io) as the feature driver. AWS IoT Greengrass uses the same building blocks to qualify software changes on various devices. For more information, see [Greengrass Testing Framework on Github](https://github.com/aws-greengrass/aws-greengrass-testing/tree/dev_v1).
GTF is implemented using Cucumber, a tool used to run automated tests, to encourage a Behavior-Driven Development (BDD) of the components. In Cucumber, the features of this system are outlined in a special type of file called `feature`. Each feature is described in a human-readable format called scenarios which are specifications that can be converted into automated tests. Each scenario is outlined as a series of steps that define the interactions and outcomes of this system under test using a domain-specific language called Gherkin. A [Gherkin step](https://cucumber.io/docs/gherkin/reference/#steps) is linked to the programming code using a method called step definition which hard wires the specification to the test flow. Step definitions in GTF are implemented with Java.
**Topics**
+ [How it works](#gg-testing-framework-how-gtf-works)
+ [Changelog](#gtf-changelog)
+ [Greengrass Testing Framework configuration options](configuration-options-gtf.md)
+ [Tutorial: Run end-to-end tests using Greengrass Testing Framework and Greengrass Development Kit](run-e2e-tests-tutorial.md)
+ [Tutorial: Use a confidence test from the confidence test suite](confidence-tests-tutorial.md)
## How it works
AWS IoT Greengrass distributes the GTF as a standalone JAR that consists of several Java modules. To use GTF for end-to-end testing of components, you must implement the tests within a Java project. Adding the testing standable JAR as a dependency in your Java project enables you to use the existing functionality of the GTF and extend it by writing your own custom test cases. To run the custom test cases, you can build your Java project and run the target JAR with the configuration options described in [Greengrass Testing Framework configuration options](configuration-options-gtf.md).
### GTF standalone JAR
Greengrass uses Cloudfront as a [Maven](https://maven.apache.org/) repository to host different versions of the GTF standalone JAR. For a full list of GTF versions, see [GTF releases](https://github.com/aws-greengrass/aws-greengrass-testing/releases).
GTF standalone JAR includes the following modules. It is not limited to only these modules. You can pick and choose each of these dependencies separately in your project or include all of them at once with the [testing standalone JAR file](https://github.com/aws-greengrass/aws-greengrass-testing/tree/dev_v1/aws-greengrass-testing-standalone).
+ `aws-greengrass-testing-resources`: This module provides abstraction for managing the lifecycle of an AWS resource during the course of a test. You can use this to define your custom AWS resources using `ResourceSpec` abstraction so GTF can take care of creation and removal of those resources for you.
+ `aws-greengrass-testing-platform`: This module provides platform-level abstraction for the device under test during the test lifecycle. It contains APIs used to interact with the OS independent of the platform and can be used to simulate the commands running in the device shell.
+ `aws-greengrass-testing-components`: This module consists of sample components that are used for testing the Greengrass core features such as deployments, IPC, and other features.
+ `aws-greengrass-testing-features`: This module consists of reusable common steps and their definitions which are used for testing within in the Greengrass environment.
**Topics**
+ [How it works](#gg-testing-framework-how-gtf-works)
+ [Changelog](#gtf-changelog)
+ [Greengrass Testing Framework configuration options](configuration-options-gtf.md)
+ [Tutorial: Run end-to-end tests using Greengrass Testing Framework and Greengrass Development Kit](run-e2e-tests-tutorial.md)
+ [Tutorial: Use a confidence test from the confidence test suite](confidence-tests-tutorial.md)
## Changelog
The following table describes the changes in each version of the GTF. For more information, see the [GTF Releases page](https://github.com/aws-greengrass/aws-greengrass-testing/releases) on GitHub.
| **Version** | **Changes** |
| --- | --- |
| 1.2.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/gg-testing-framework.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/gg-testing-framework.html) |
| 1.1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/gg-testing-framework.html) |
| 1.0.0 | Initial version. |
# Greengrass Testing Framework configuration options
## GTF configuration options
Greengrass Testing Framework (GTF) enables you to configure certain parameters during the launch of the end-to-end testing process to orchestrate the test flow. You can specify these configuration options as CLI arguments for the GTF standalone JAR.
GTF version 1.1.0 and later provides the following configuration options.
+ `additional-plugins` – (Optional) Additional Cucumber plugins
+ `aws-region` – Targets specific regional endpoints for AWS services. Defaults to what the AWS SDK discovers.
+ `credentials-path` – Optional AWS profile credentials path. Defaults to credentials discovered on host environment.
+ `credentials-path-rotation` – Optional rotation duration for AWS credentials. Defaults to 15 minutes or `PT15M`.
+ `csr-path` – The path for the CSR using which the device certificate will be generated.
+ `device-mode` – The target device under test. Defaults to local device.
+ `env-stage` – Targets the deployment environment of Greengrass. Defaults to production.
+ `existing-device-cert-arn` – The arn of an existing certificate that you want to use as a device certificate for Greengrass.
+ `feature-path` – File or directory containing additional feature files. Default is no additional feature files are used.
+ `gg-cli-version` – Overrides the version of the Greengrass CLI. Defaults to the value found in `ggc.version`.
+ `gg-component-bucket` – The name of an existing Amazon S3 bucket that houses Greengrass components.
+ `gg-component-overrides` – A list of Greengrass component overrides.
+ `gg-persist` – A list of test elements to persist after a test run. Default behavior is to persist nothing. Accepted values are: `aws.resources`, `installed.software`, and `generated.files`.
+ `gg-runtime` – A list of values to influence how the test interacts with testing resources. These values supersede the `gg.persist` parameter. If the default is empty, it assumes all testing resources are manged by test case, including the installed Greengrass runtime. Accepted values are: `aws.resources`, `installed.software`, and `generated.files`.
+ `ggc-archive` – The path to the archived Greengrass nucleus component.
+ `ggc-install-root` – Directory to install the Greengrass nucleus component. Defaults to test.temp.path and test run folder.
+ `ggc-log-level` – Set the Greengrass nucleus log level for the test run. Default is "INFO".
+ `ggc-tes-rolename` – The IAM role that AWS IoT Greengrass Core will assume to access AWS services. If a role with given name does not exist then one will be created and default access policy.
+ `ggc-trusted-plugins` – The comma separate list of the paths (on host) of the trusted plugins that need to added to Greengrass. To provide the path on the DUT itself, prefix the path with 'dut:'
+ `ggc-user-name` – The user:group posixUser value for the Greengrass nucleus. Defaults to the current username that is logged in.
+ `ggc-version` – Overrides the version of the running Greengrass nucleus component. Defaults to the value found in ggc.archive.
+ `log-level` – Log level of the test run. Defaults to "INFO".
+ `parallel-config` – Set of batch index and number of batches as a JSON String. Default value of batch index is 0 and number of batches is 1.
+ `proxy-url` – Configure all tests to route traffic through this URL.
+ `tags` – Only run feature tags. Can be intersected with '&'
+ `test-id-prefix` – A common prefix applied to all test specific resources including AWS resource names and tags. Default is a "gg" prefix.
+ `test-log-path` – Directory that will contain the results of the entire test run. Defaults to "testResults".
+ `test-results-json` – Flag to determine if a resulting Cucumber JSON report is generated written to disk. Defaults to true.
+ `test-results-log` – Flag to determine if the console output is generated written to disk. Defaults to false.
+ `test-results-xml` – Flag to determine if a resulting JUnit XML report is generated written to disk. Defaults to true.
+ `test-temp-path` – Directory to generate local test artifacts. Defaults to a random temp directory prefixed with gg-testing.
+ `timeout-multiplier` – Multiplier provided to all test timeouts. Default is 1.0.
# Tutorial: Run end-to-end tests using Greengrass Testing Framework and Greengrass Development Kit
AWS IoT Greengrass Testing Framework (GTF) and Greengrass Development Kit (GDK) offer developers ways to run end-to-end tests. You can complete this tutorial to initialize a GDK project with a component, initialize a GDK project with an end-to-end test module, and build a custom test case. After you build your custom test case, you can then run the test.
In this tutorial, you do the following:
1. Initialize a GDK project with a component.
1. Initialize a GDK project with an end-to-end test module.
1. Build a custom test case.
1. Add a tag to the new test case.
1. Build the test JAR.
1. Run the test.
**Topics**
+ [Prerequisites](#run-e2e-tests-tutorial-prerequisites)
+ [Step 1: Initialize a GDK project with a component](#init-gdk-with-component)
+ [Step 2: Initialize a GDK project with an end-to-end test module](#init-gdk-with-e2e-test)
+ [Step 3: Build a custom test case](#run-e2e-tests-tutorial-instructions)
+ [Step 4: Add a tag to the new test case](#add-tag-to-test-case)
+ [Step 5: Build the test JAR](#build-test-jar)
+ [Step 6: Run the test](#run-test-gtf)
+ [Example: Build a custom test case](#build-test-case-example)
## Prerequisites
To complete this tutorial, you need the following:
+ GDK version 1.3.0 or later
+ Java
+ Maven
+ Git
## Step 1: Initialize a GDK project with a component
+ Initialize an empty folder with a GDK project. Download the `HelloWorld` component implemented in Python by running the following command.
```
gdk component init -t HelloWorld -l python -n HelloWorld
```
This command creates a new directory named `HelloWorld` in the current directory.
## Step 2: Initialize a GDK project with an end-to-end test module
+ GDK enables you to download the testing module template consisting of a feature and step implementation. Run the following command to open the `HelloWorld` directory and initialize the existing GDK project using a testing module.
```
cd HelloWorld
gdk test-e2e init
```
This command creates a new directory named `gg-e2e-tests` within the `HelloWorld` directory. This test directory is a [Maven](https://maven.apache.org/) project which has a dependency on the Greengrass testing standalone JAR.
## Step 3: Build a custom test case
Writing a custom test case broadly consists of two steps: create a feature file with a test scenario and implement step definitions. For an example of building a custom test case, see [Example: Build a custom test case](#build-test-case-example). Use the following steps to build your custom test case:
1. Create a feature file with a test scenario
A feature typically describes a specific functionality of the software that is being tested. In Cucumber, each feature is specified as an individual feature file with a title, a detailed description, and one or more examples of specific cases called scenarios. Each scenario consists of a title, a detailed description, and a series of steps that define the interactions and expected outcomes. Scenarios are written in a structured format using "given," "when," and "then" keywords.
1. Implement step definitions
A step definition links the [Gherkin step](https://cucumber.io/docs/gherkin/reference/#steps) in plain language to the programmatic code. When Cucumber identifies a Gherkin step in a scenario, it will look for a matching step definition to run.
## Step 4: Add a tag to the new test case
+ You can assign tags to the features and scenarios to organize the test process. You can use tags to categorize the subsets of scenarios and also select hooks conditionally to run. Features and scenarios can have multiple tags separated by a space.
In this example, we are using the `HelloWorld` component.
In the feature file, add a new tag named `@HelloWorld` beside the `@Sample` tag.
```
@Sample @HelloWorld
Scenario: As a developer, I can create a component and deploy it on my device
....
```
## Step 5: Build the test JAR
1. Build the component. You must build the component before building the test module.
```
gdk component build
```
1. Build the test module using the following command. This command will build the testing JAR in the `greengrass-build` folder.
```
gdk test-e2e build
```
## Step 6: Run the test
When you run a custom test case, the GTF automates the lifecycle of the test along with managing resources that were created during the test. It first provisions a device under test (DUT) as an AWS IoT thing and installs the Greengrass core software on it. It will then create a new component named `HelloWorld` using the recipe specified in that path. The `HelloWorld` component is then deployed onto the core device through a Greengrass thing deployment. It will then be verified if the deployment is successful. The deployment status will changed to `COMPLETED` within 3 minutes if the deployment is successful.
1. Go to the `gdk-config.json` file in the project directory to target the tests with the `HelloWorld` tag. Update the the `test-e2e` key using the following command.
```
"test-e2e":{
"gtf_options" : {
"tags":"HelloWorld"
}
}
```
1. Before running the tests, you must provide AWS credentials to the host device. GTF uses these credentials to manage the AWS resources during the testing process. Make sure the role you provide has permissions to automate the necessary operations that are included in the test.
Run the following commands to provide the AWS credentials.
1.
------
#### [ Linux or Unix ]
```
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
```
------
#### [ Windows Command Prompt (CMD) ]
```
set AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
set AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
```
------
#### [ PowerShell ]
```
$env:AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
$env:AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
```
------
1. Run the test using the following command.
```
gdk test-e2e run
```
This command downloads the latest version of the Greengrass nucleus in the `greengrass-build` folder and runs tests using it. This command also targets only the scenarios with the `HelloWorld` tag and generates a report for those scenarios. You will see the AWS resources that were created during this test are discarded at the end of the test.
## Example: Build a custom test case
**Example**
The downloaded testing module in the GDK project consists of a sample feature and a step implementation file.
In the following example, we create a feature file for testing the thing deployment feature of the Greengrass software. We partially test the functionality of this feature with a scenario that performs deployment of a component through the Greengrass AWS Cloud. This is a series of steps that help us to understand the interactions and expected outcomes of this use case.
1.
**Create a feature file**
Navigate to the `gg-e2e-tests/src/main/resources/greengrass/features` folder in the current directory. You can find the sample `component.feature` that looks like the following example.
In this feature file, you can test the thing deployment feature of the Greengrass software. You can partially test the functionality of this feature with a scenario that performs a deployment of a component through the Greengrass cloud. The scenario is a series of steps that help with understanding the interactions and expected outcomes of this use case.
```
Feature: Testing features of Greengrassv2 component
Background:
Given my device is registered as a Thing
And my device is running Greengrass
@Sample
Scenario: As a developer, I can create a component and deploy it on my device
When I create a Greengrass deployment with components
HelloWorld | /path/to/recipe/file
And I deploy the Greengrass deployment configuration
Then the Greengrass deployment is COMPLETED on the device after 180 seconds
And I call my custom step
```
GTF contains the step definitions of all of the following steps, except for the step named: `And I call my custom step`.
1.
**Implement step definitions**
GTF standalone JAR contains the step definitions of all of the steps except for one step: `And I call my custom step`. You can implement this step in the testing module.
Navigate to the source code of the testing file. You can link your custom step using a step definition by using the following command.
```
@And("I call my custom step")
public void customStep() {
System.out.println("My custom step was called ");
}
```
# Tutorial: Use a confidence test from the confidence test suite
AWS IoT Greengrass Testing Framework (GTF) and Greengrass Development Kit (GDK) offer developers ways to run end-to-end tests. You can complete this tutorial to initialize a GDK project with a component, initialize a GDK project with an end-to-end test module, and use a confidence test from the confidence test suite. After you build your custom test case, you can then run the test.
A confidence test is a generic test provided by Greengrass that validates fundamental component behaviors. These tests can be modified or extended to fit more specific component needs.
For this tutorial we will be using a HelloWorld component. If you are using another component, replace the HelloWorld component with your component.
In this tutorial, you do the following:
1. Initialize a GDK project with a component.
1. Initialize a GDK project with an end-to-end test module.
1. Use a test from the confidence test suite.
1. Add a tag to the new test case.
1. Build the test JAR.
1. Run the test.
**Topics**
+ [Prerequisites](#confidence-tests-tutorial-prerequisites)
+ [Step 1: Initialize a GDK project with a component](#init-gdk-with-component)
+ [Step 2: Initialize a GDK project with an end-to-end test module](#init-gdk-with-e2e-test)
+ [Step 3: Use a test from the confidence test suite](#confidence-tests-tutorial-instructions)
+ [Step 4: Add a tag to the new test case](#add-tag-to-test-case)
+ [Step 5: Build the test JAR](#build-test-jar)
+ [Step 6: Run the test](#run-test-gtf)
+ [Example: Use a confidence test](#build-confidence-test-case-example)
## Prerequisites
To complete this tutorial, you need the following:
+ GDK version 1.6.0 or later
+ Java
+ Maven
+ Git
## Step 1: Initialize a GDK project with a component
+ Initialize an empty folder with a GDK project. Download the `HelloWorld` component implemented in Python by running the following command.
```
gdk component init -t HelloWorld -l python -n HelloWorld
```
This command creates a new directory named `HelloWorld` in the current directory.
## Step 2: Initialize a GDK project with an end-to-end test module
+ GDK enables you to download the testing module template consisting of a feature and step implementation. Run the following command to open the `HelloWorld` directory and initialize the existing GDK project using a testing module.
```
cd HelloWorld
gdk test-e2e init
```
This command creates a new directory named `gg-e2e-tests` within the `HelloWorld` directory. This test directory is a [Maven](https://maven.apache.org/) project which has a dependency on the Greengrass testing standalone JAR.
## Step 3: Use a test from the confidence test suite
Writing a confidence test case consists of using the provided feature file and, if needed, modifying the scenarios. For an example of using a confidence test, see [Example: Build a custom test case](run-e2e-tests-tutorial.md#build-test-case-example). Use the following steps to use a confidence test:
+ Use the provided feature file.
Navigate to `gg-e2e-tests/src/main/resources/greengrass/features` folder in the current directory. Open the sample `confidenceTest.feature` file to use the confidence test.
## Step 4: Add a tag to the new test case
+ You can assign tags to the features and scenarios to organize the test process. You can use tags to categorize the subsets of scenarios and also select hooks conditionally to run. Features and scenarios can have multiple tags separated by a space.
In this example, we are using the `HelloWorld` component.
Each scenario is tagged with `@ConfidenceTest`. Change or add tags if you want to run only a subset of the test suite. Each test scenario is described at the top of each confidence test. The scenario is a series of steps that help with understanding the interactions and expected outcomes of each test case. You can extend these tests by adding your own steps or by modifying the existing ones.
```
@ConfidenceTest
Scenario: As a Developer, I can deploy GDK_COMPONENT_NAME to my device and see it is working as expected
....
```
## Step 5: Build the test JAR
1. Build the component. You must build the component before building the test module.
```
gdk component build
```
1. Build the test module using the following command. This command will build the testing JAR in the `greengrass-build` folder.
```
gdk test-e2e build
```
## Step 6: Run the test
When you run a confidence test, the GTF automates the lifecycle of the test along with managing resources that were created during the test. It first provisions a device under test (DUT) as an AWS IoT thing and installs the Greengrass core software on it. It will then create a new component named `HelloWorld` using the recipe specified in that path. The `HelloWorld` component is then deployed onto the core device through a Greengrass thing deployment. It will then be verified if the deployment is successful. The deployment status will changed to `COMPLETED` within 3 minutes if the deployment is successful.
1. Go to the `gdk-config.json` file in the project directory to target the tests with the `ConfidenceTest` tag or whichever tag yo8u specified in Step 4. Update the the `test-e2e` key using the following command.
```
"test-e2e":{
"gtf_options" : {
"tags":"ConfidenceTest"
}
}
```
1. Before running the tests, you must provide AWS credentials to the host device. GTF uses these credentials to manage the AWS resources during the testing process. Make sure the role you provide has permissions to automate the necessary operations that are included in the test.
Run the following commands to provide the AWS credentials.
1.
------
#### [ Linux or Unix ]
```
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
```
------
#### [ Windows Command Prompt (CMD) ]
```
set AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
set AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
```
------
#### [ PowerShell ]
```
$env:AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
$env:AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
```
------
1. Run the test using the following command.
```
gdk test-e2e run
```
This command downloads the latest version of the Greengrass nucleus in the `greengrass-build` folder and runs tests using it. This command also targets only the scenarios with the `ConfidenceTest` tag and generates a report for those scenarios. You will see the AWS resources that were created during this test are discarded at the end of the test.
## Example: Use a confidence test
**Example**
The downloaded testing module in the GDK project consists of a provided feature file.
In the following example, we use a feature file for testing the thing deployment feature of the Greengrass software. We partially test the functionality of this feature with a scenario that performs deployment of a component through the Greengrass AWS Cloud. This is a series of steps that help us to understand the interactions and expected outcomes of this use case.
+
**Use the provided feature file.**
Navigate to the `gg-e2e-tests/src/main/resources/greengrass/features` folder in the current directory. You can find the sample `confidenceTest.feature` that looks like the following example.
```
Feature: Confidence Test Suite
Background:
Given my device is registered as a Thing
And my device is running Greengrass
@ConfidenceTest
Scenario: As a Developer, I can deploy GDK_COMPONENT_NAME to my device and see it is working as expected
When I create a Greengrass deployment with components
| GDK_COMPONENT_NAME | GDK_COMPONENT_RECIPE_FILE |
| aws.greengrass.Cli | LATEST |
And I deploy the Greengrass deployment configuration
Then the Greengrass deployment is COMPLETED on the device after 180 seconds
# Update component state accordingly. Possible states: {RUNNING, FINISHED, BROKEN, STOPPING}
And I verify the GDK_COMPONENT_NAME component is RUNNING using the greengrass-cli
```
Each test scenario is described at the top of each confidence test. The scenario is a series of steps that help with understanding the interactions and expected outcomes of each test case. You can extend these tests by adding your own steps or by modifying the existing ones. Each of the scenarios include comments that help you to make these adjustments.