Greengrass Component Configuration: Remove Obsolete Gateway Keys with Reset Before Merge

An industrial collector can keep an obsolete setting after its deployment file stops mentioning that setting. Before treating this as a restart failure, compute the configuration update against the component’s existing state. In Greengrass V2, a deployment configuration is a patch, so the proposed file may describe only part of the resulting configuration.

This article uses AWS’s Greengrass V2 documentation checked on 19 October 2026. The collector, topics and values are invented. The example is a semantic walkthrough; no cloud deployment, gateway configuration change or Greengrass runtime test was performed.

Start with the baseline that actually exists

The ComponentConfigurationUpdate API distinguishes an installed component’s current configuration from the defaults used on first installation. Omitted merge keys retain their existing values. Consequently, identical merge input can produce different effective configurations on two gateways with different histories.

For a proposed collector, let the recipe defaults be:

{
  "pollMs": "1000",
  "topics": ["lab/base"],
  "label": "line-default"
}

Suppose an installed instance instead has this current configuration:

{
  "pollMs": "250",
  "topics": ["lab/a", "lab/b"],
  "label": "commissioning",
  "legacyScale": "0.1",
  "siteLabel": "west",
  "note": "temporary"
}

The intended change is precise: restore the default polling interval, remove legacyScale, replace the subscribed-topic list and retain an explicit null note. Preserve the existing label and site label. Writing these intentions first prevents a short merge object from being mistaken for a complete desired-state declaration.

Derive reset before merge

AWS’s configuration-update guide specifies reset before merge. Reset paths use JSON Pointer: a defaulted value returns to its default, while a value with no default is removed. Lists reset as whole values. Merge then assigns the requested changes, including whole-list replacement and null values.

For this example, prepare these reset paths:

["/legacyScale", "/pollMs", "/topics"]

Then prepare this logical merge object:

{"topics": ["lab/c"], "note": null}

After reset, legacyScale is absent, pollMs is "1000", and topics temporarily returns to ["lab/base"]. The other current values remain. Merge then replaces that list with ["lab/c"] and sets note to null. The calculated final installed-state result is:

{
  "pollMs": "1000",
  "topics": ["lab/c"],
  "label": "commissioning",
  "siteLabel": "west",
  "note": null
}

The intermediate reset list is included to expose ordering. For this particular patch, merging the complete replacement list would already replace the old topics without resetting /topics. Retaining that path in the walkthrough demonstrates that the later merge wins; it is not an additional requirement for every list update.

Original state-transformation diagram. All configurations are synthetic and the result is calculated, not observed on a gateway.

Treat omission, null and absence separately

The consumer should distinguish a key that is absent from a key whose value is null. In the fixture, legacyScale disappears because its reset target has no recipe default. note remains present because null is the value requested by merge. Check presence separately from value when reviewing the result.

Likewise, leaving legacyScale out of merge would not express removal from the installed configuration. A team comparing only the submitted merge object with the desired object could overlook the obsolete setting indefinitely. Review the resulting object instead, with an explicit list of keys that must be absent.

Topic replacement also needs a concrete expected list. The requested ["lab/c"] does not describe appending one topic to ["lab/a", "lab/b"]. If individual entries need independent patch ownership, consider a schema with stable object keys, then assess that schema change with the collector’s parser and consumers.

Compare an installed device with first installation

Apply the same logical update to the stated recipe defaults rather than the installed-state object. The calculated result contains pollMs "1000", topics ["lab/c"], label "line-default" and note null. It has no site label, because that key existed only in the installed baseline.

This difference explains why a clean-device check can miss a migration defect. A useful review therefore includes both baselines. If the intended result must match across them, identify which additional values the patch must explicitly establish. Do not assume a recipe version change erases previously configured settings merely because they are omitted from the patch.

AWS also documents an entire-configuration reset using [""]. Its breadth deserves a separate decision: in this fixture it would discard the intentionally retained site label and restore the default label before merge. A whole reset should not replace careful reasoning about the specific obsolete key.

Check representation and application acceptance

The API’s merge member is a serialized JSON string, whereas the examples above show its logical object for readability. Generate that string with a JSON serializer and inspect the enclosing request structure; avoid hand-escaping a growing deployment document.

The proposed review record should include recipe version, defaults, captured current state, reset paths, logical merge and calculated final state. Assert the removed key’s absence, restored interval, exact topic list, null note and preserved labels. Repeat from the first-install baseline and explain every difference.

Finally, have the collector validate allowed topic names, required fields and its polling-interval representation. Correct patch semantics can still produce a configuration the application rejects. The handover is complete when the intended effective object and the component’s accepted schema agree, with runtime verification recorded separately from this calculation.