EdgeIQ – Update Greengrass Core

With your EgdeIQ account you can manage your devices such as your IG60 gateway. With that gateway you may want to update the AWS Greengrass Core. This document details that process.

As an overview, we’ll be selecting a gateway device and then issuing a shell command via a software update action on EdgeIQ.

Greeengrass Core Update Sequence of Events

The following describes the sequence of operations when performing an update of the Greengrass core:

  • The IG60 is running with an existing Greengrass core
  • The updating client (e.g., Lambda function) issues the request to update via the StartCoreDownload() method
  • The Provisioning service receives a request to download a new core version via the StartCoreDownload() method
    • If the request is invalid (e.g., bad parameters), the Provisioning service returns a failure to the call and the operation is complete (failed)
    • Otherwise, the Provisioning service returns PROV_INPROGRESS_DOWNLOADING to the call indicating the request is in progress
  • The Provisioning service attempts to download the JSON descriptor and core tarball ONLY (no configuration) based on the request parameters
    • If a failure occurs while connecting or downloading, or a signature mismatch occurs, the Provisioning service indicates failure via the StateChanged signal and the operation is complete (failure)
  • The Provisioning service create a copy of the Greengrass security certificates and configuration, to be used after the new core has been installed
  • The Provisioning service notifies the clients that the update is ready (PROV_INPROGRESS_UPDATE_READY) via the StateChanged signal
  • The updating client receives the indication via the StateChanged signal and completes any additional work before the Core goes down (e.g., notify cloud via MQTT message)
  • The updating client indicates it is OK to proceed by calling the PerformCoreUpdate method. (Immediately after this call the core will no longer be available until the update has completed.)
  • The Provisioning service receives the request to proceed via the PerformCoreUpdate() method, and does the following:
    • Stop the current Grengrass core daemon process
    • Remove the entire Greengrass installation directory (/gg/greengrass)
    • Extract the core tarball, replace the previous configuration and certificates
    • Restart the Greengrass core service
    • Indicate that the procedure is complete (PROV_COMPLETE_SUCCESS) via the StateChanged signal

GDBus Command

The actual command to perform the update leverages the gdbus utility which handles D-Bus API calls. An example of the command is below. Note that you will need to alter this example command. The changes needed will depend on if you’re using Ezurio’s Bluegrass demo platform or your own AWS provisioning server. The parameters to change are highlighted in yellow, below.

gdbus call --system \

--dest com.lairdtech.IG.ProvService \

--object-path /com/lairdtech/IG/ProvService \

--method com.lairdtech.IG.ProvInterface.StartProvisioning \

'https://dng7q89c4hj8l.cloudfront.net/623c0b600c.json' \

"{'username': <'markc'>, 'password': <'S3cr3tP@ssw0rd'>}"

Alter Command for Bluegrass

  • URL for JSON provisioning file
  • User/Password
    • Replace the “Ezurio” values with the username and password that you registered with on the Ezurio Bluegrass demo site.

Alter Command for Customer Provisioning Server

  • URL for JSON provisioning file
    • The URL should be the AWS Cloudfront address you have (or similar) that points to your JSON provisioning file.
    • You can typically find this URL in your AWS CloudFormation stack for your provisioning server.
    • The following is an example provisioning link: https://dng7q89c4hj8l.cloudfront.net/623c0b600c.json
  • User/Password
    • Replace the “laird” values with the username and password that you created during the process of setting up your provisioning server in AWS CloudFormation.

Push GDBus Command with EdgeIQ

In this section we will put our customized gdbus command into an Edge IQ software update package which we will then push down through a software update command. This will trigger the gateway device to run the gdbus command, thereby instructing it to go and fetch a Greengrass Core update from a provisioning server.

Create a Software Package on EdgeIQ

Once you are logged into your EdgeIQ account please navigate to the Software Packages page on the sidebar under DeviceOps by clicking “Software”. Here you will find all of your current software packages. Let's create a new one by hitting the blue “Create Package” button in the toolbar near the top of the page.

Create Software Package

Now, you’ll be presented with a page where you can set configure the following parameters for your software package.

  • Name
    • Enter a name of your choice for the package. In our example we use ‘Deploy GG Core’.
  • Executable Script
    • Here you will copy the gdbus command that you modified in the previous section of this document.
  • Reboot Device After Installation
    • This can be left off.
  • Device Type
    • For an IG60 gateway the device type will be LCI Sentrius IG60.
    • In the event that you are using a different device then please select the appropriate type here.
  • Upload Files
    • N/A for this particular use case.

When you have sufficiently filled out the parameters of the software package you can hit the “Create Package” button.

Software Package Details

You should now see your newly created software package. In this case our example was called “Deploy GG Core”.

Software Package Complete

You can verify that your gdbus command looks correct by clicking on the blue icon in your software package.

Verify Gdbus Command

Push a Software Package to your Device

Now that we have created a software package containing our custom gdbus command (for updating your Greengrass Core) we can push that package to a device. Let’s start by navigating to your devices by clicking on “Devices” in the sidebar under “DeviceOps”. From here you can select the particular device you want to push your update to.

Select Device

With your device now being displayed go ahead and hit the “Command” button in the top left of the device’s control panel.

Create Command

From here we will select an action to perform on the gateway device. Let’s select “Update Software”. This will allow us to push a specific software package that we specify in the dropdown menu. In our example we have selected the ‘Deploy GG Core’ package we created in the previous steps of this document. The software package you select should contain the gdbus command.

Now, you can hit the blue “Update Software” button to push this command down to the gateway device. Once the gateway has the command it will begin updating the Greengrass Core. Upon completion it will start running Greengrass.

Select Command Action

Provisioning Status Codes

Below is a table of the possible status codes that can be returned by the device.

Value Status Description
0 PROV_COMPLETE_SUCCESS Device is provisioned, or provisioning has completed successfully
1 PROV_UNPROVISIONED Device is not provisioned
2 PROV_INPROGRESS_DOWNLOADING Provisioning started, downloading configuration
3 PROV_INPROGESS_APPLYING Provisioning started, applying configuration
4 PROV_INPROGRESS_REMOVING Provisioning started, removing existing configuration
5 PROV_INPROGRESS_UPDATE_READY Requested core update is downloaded, verified, and ready to apply
-1 PROV_FAILED_INVALID Provisioning failed, invalid configuration (e.g., Greengrass not installed)
-2 PROV_FAILED_CONNECT Provisioning failed, connection failure
-3 PROV_FAILED_AUTH Provisioning failed, authentication failure
-4 PROV_FAILED_TIMEOUT Provisioning failed, timeout
-5 PROV_FAILED_NOT_FOUND Provisioning failed, file not found
-6 PROV_FAILED_BAD_CONFIG Provisioning failed, descriptor or signature was invalid
-7 PROV_FAILED_UNKNOWN Provisioning failed, unknown failure