deployment

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 <thing-group>]
    [--merge "<component-name>=<component-version>"]...
    [--runWith "<component-name>:posixUser=<user-name>[:<group-name>]"]...
    [--systemLimits "{component-system-resource-limits}]"]...
    [--remove <component-name>,...]
    [--failure-handling-policy <policy name[ROLLBACK, DO_NOTHING]>]

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/<component-name>/<component-version>/<artifacts>

• --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 <component>=<version>. 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 <component>:{posixUser|windowsUser}=<user>[:<=posixGroup>]. For example, you might specify HelloWorld:posixUser=ggc_user:ggc_group or HelloWorld:windowsUser=ggc_user. Use a separate argument for each additional option to specify.

  For more information, see Configure the user that runs components.

• --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 Amazon 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.

  This feature is available for v2.4.0 and later of the Greengrass nucleus component and Greengrass CLI on Linux core devices. Amazon 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. 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 <component-name> --groupId <group-name>

  Earlier than v2.4.0

  --remove <component-name> --groupId thinggroup/<group-name>

• --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.

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

Synopsis

greengrass-cli deployment cancel
    -i <deployment-id>

Arguments

-i. The unique identifier of the deployment to cancel. The deployment ID is returned in the output of the create command.

Output

• None

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

Synopsis

greengrass-cli deployment status -i <deployment-id>

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: <Detailed deployment status>
Deployment Error Stack: List of error codes
Deployment Error Types: List of error types
Failure Cause: Cause