Invalid steps workflow collection about iot-hub-device-update HOT 4 CLOSED

Summary

The first is trying to deep copy handlerProperties from the update manifest, which is needed by apt content handler. In fact, it needs "installedCriteria" property in the handlerProperties.

Resolution

The update manifest from the logs shows there is no "handlerProperties" property for step 0:

    "instructions": {
        "steps": [
            {
                "handler": "microsoft\/apt:1",
                "files": [
                    "fb42001e3d0d13a3b"
                ]
            }
        ]
    }

Instead, the import manifest should have something like:

    "instructions": {
        "steps": [
            {
                "handler": "microsoft\/apt:1",
                "handlerProperties": {
                    "installedCriteria": "1.0"
                },
                "files": [
                    "fb42001e3d0d13a3b"
                ]
            }
        ]
    }

Explanation

It uses "installedCriteria" to determine if the update needs to be installed or not. Ideally, the APT content handler should query APT/dpkg to determine if the packages in the apt manifest are installed or not, but since it can be set of package adds and deletions (by prefixing - to the package name), opted for the existing "installedCriteria" concept, which is an abstract version that is not related to the packages or individual package versions.

When apt packages are installed (or removed if - prefix is used in apt manifest), then it appends a file at /var/lib/adu/installedcriteria with the latest installed installedCriteria. To determine if IsInstalled is true, it will look to see if the current installedCriteria exists in this file.

Possibly Confusing Documentation

https://learn.microsoft.com/en-us/azure/iot-hub-device-update/import-schema#inlinestep-object that shows handlerProperties is not required which is true in general for a custom content handler, but for APT and other 1st party content handlers, they require at least this:

"handlerProperties": {
    "installedCriteria": "1.0"
},

We're looking into how to make this less confusing.

Detailed Analysis

-2143289331 is hex ffff ffff 8040 000d

which from https://github.com/Azure/iot-hub-device-update/blob/main/src/inc/aduc/result.h#L1321 is:
/**

• @brief ADUC_ERC_UTILITIES_WORKFLOW_UTIL_COPY_UPDATE_ACTION_COPY_HANDLER_PROPERTIES_FAILED, ERC Value: 2151677965 (0x8040000d)
  */
  #define ADUC_ERC_UTILITIES_WORKFLOW_UTIL_COPY_UPDATE_ACTION_COPY_HANDLER_PROPERTIES_FAILED MAKE_ADUC_EXTENDEDRESULTCODE_FOR_COMPONENT_ADUC_COMPONENT_WORKFLOW_UTIL(13)

From steps-handler.20221103-155849.log:

2022-11-03T15:58:49.3607Z 713[713] [E] Cannot copy 'handlerProperties'. [workflow_create_from_inline_step]
2022-11-03T15:58:49.3607Z 713[713] [E] ERROR: failed to create workflow for level:0 step#0. [PrepareStepsWorkflowDataObject]

This corresponds to code in

from iot-hub-device-update.

Summary

The first is trying to deep copy handlerProperties from the update manifest, which is needed by apt content handler. In fact, it needs "installedCriteria" property in the handlerProperties.

Resolution

The update manifest from the logs shows there is no "handlerProperties" property for step 0:

    "instructions": {
        "steps": [
            {
                "handler": "microsoft\/apt:1",
                "files": [
                    "fb42001e3d0d13a3b"
                ]
            }
        ]
    }

Instead, the import manifest should have something like:

    "instructions": {
        "steps": [
            {
                "handler": "microsoft\/apt:1",
                "handlerProperties": {
                    "installedCriteria": "1.0"
                },
                "files": [
                    "fb42001e3d0d13a3b"
                ]
            }
        ]
    }

Explanation

It uses "installedCriteria" to determine if the update needs to be installed or not. Ideally, the APT content handler should query APT/dpkg to determine if the packages in the apt manifest are installed or not, but since it can be set of package adds and deletions (by prefixing - to the package name), opted for the existing "installedCriteria" concept, which is an abstract version that is not related to the packages or individual package versions.

When apt packages are installed (or removed if - prefix is used in apt manifest), then it appends a file at /var/lib/adu/installedcriteria with the latest installed installedCriteria. To determine if IsInstalled is true, it will look to see if the current installedCriteria exists in this file.

Possibly Confusing Documentation

https://learn.microsoft.com/en-us/azure/iot-hub-device-update/import-schema#inlinestep-object that shows handlerProperties is not required which is true in general for a custom content handler, but for APT and other 1st party content handlers, they require at least this:

"handlerProperties": {
    "installedCriteria": "1.0"
},

We're looking into how to make this less confusing.

Detailed Analysis

-2143289331 is hex ffff ffff 8040 000d

which from https://github.com/Azure/iot-hub-device-update/blob/main/src/inc/aduc/result.h#L1321 is: /**

• @brief ADUC_ERC_UTILITIES_WORKFLOW_UTIL_COPY_UPDATE_ACTION_COPY_HANDLER_PROPERTIES_FAILED, ERC Value: 2151677965 (0x8040000d)
  */
  #define ADUC_ERC_UTILITIES_WORKFLOW_UTIL_COPY_UPDATE_ACTION_COPY_HANDLER_PROPERTIES_FAILED MAKE_ADUC_EXTENDEDRESULTCODE_FOR_COMPONENT_ADUC_COMPONENT_WORKFLOW_UTIL(13)

From steps-handler.20221103-155849.log:

2022-11-03T15:58:49.3607Z 713[713] [E] Cannot copy 'handlerProperties'. [workflow_create_from_inline_step]
2022-11-03T15:58:49.3607Z 713[713] [E] ERROR: failed to create workflow for level:0 step#0. [PrepareStepsWorkflowDataObject]

This corresponds to code in

iot-hub-device-update/src/utils/workflow_utils/src/workflow_utils.c

Line 2307 in 33554d2

result.ExtendedResultCode = ADUC_ERC_UTILITIES_WORKFLOW_UTIL_COPY_UPDATE_ACTION_COPY_HANDLER_PROPERTIES_FAILED;

where it is trying to copy "handlerProperties" property.

Thank you very much for the detailed response. I used the az cli to create the update manifest, perhaps additional logic is needed there to properly create the manifest file with all required properties. I also noticed due to fat fingering that you can set an invalid update handler via the CLI.

I'll try this and let you know results.

from iot-hub-device-update.

It's working as expected - Thank you

from iot-hub-device-update.

Glad it's working. Cheers!

from iot-hub-device-update.