Differences

This shows you the differences between two versions of the page.

--- zededa:patch-envelopes [2026/07/21 19:04] – created mc
+++ zededa:patch-envelopes [2026/07/23 23:24] (current) – mc
@@ Line 14: / Line 14: @@
 attach a patch envelope to the app instance and update //just// that data. Typical scenarios:
-  * Pushing updated configuration to a running app without downtime
+  * Making updated configuration available to a running app without downtime (the app pulls it from the metadata service — nothing is pushed to the guest)
   * Rotating credentials, certs, tokens, license keys
   * Delivering site-specific or device-specific parameters to a generic image
@@ Line 21: / Line 21: @@
 You manage it from the controller (the ''PatchEnvelopeConfiguration'' API), and EVE exposes
 it to the app locally.
+===== What can the binary artifact be? =====
+You attach one or more **binary artifacts** to a patch envelope and present them to the app
+instance; the app then pulls them from the metadata service. So what can that artifact
+actually be?
+**Anything — it is an opaque blob to EVE.** EVE does not parse, validate, or execute the
+artifact; it only delivers the bytes into the app's reach. So a binary artifact can be:
+  * an ''.exe'', a shell script, a Python file
+  * a config file / YAML / JSON / ''.env''
+  * certs, keys, a license file, a token
+  * a firmware image, a tarball / zip, a small dataset, a DB seed
+  * a file with **any** extension (''.ext'', ''.bin'', ''.dat'', …) — the extension is meaningless to EVE
+  * essentially any file you would otherwise have to bake into the image
+**EVE never runs it.** For an ''.exe'', EVE transfers the bytes; the **guest app** (e.g. a
+Windows VM) is what pulls it and executes it. EVE is agnostic about what the blob is or which
+OS consumes it.
+==== Can I store the binary in my datastore and just consume it via the patch envelope? ====
+**Yes — that is the //external artifact// model** (see [[#inline vs. external artifacts]]
+below), and it is the right choice for anything larger than the inline limit (e.g. an ''.exe'').
+  * Put the binary in a **datastore**, reference it from the patch envelope, and the app consumes it.
+  * The app **still pulls it** via the metadata service (''description.json'' → download URL); external artifacts appear under ''VolumeRefs''. EVE downloads the volume host-side, but the app is what retrieves/uses it — it is **not** auto-injected into the guest.
+  * External artifacts **inherit the datastore's ACLs** — the datastore must be reachable and permissioned from the device, same as image datastores.
+> The exact datastore types supported for patch-envelope external artifacts (HTTP/HTTPS, S3,
+> Azure blob, container registry, …) may be narrower than the full image-datastore list —
+> verify against the ''PatchEnvelopeConfiguration'' API for your zedcloud version.
 ===== Does the app need to constantly poll http://169.254.169.254/... ? =====
-**No — you do //not// need constant/continuous polling.** That is the key point.
+The patch envelope metadata service is **pull-only**. There is **no push, no
+notification, no interrupt** to the guest. So if the app wants to //discover// that a
+new config exists, it **has to poll** ''description.json''. There is no way around that.
-The metadata service at ''169.254.169.254'' is a **pull, on-demand** interface, not a stream
+Two different things are worth separating:
-you have to hammer. The normal pattern is:
-  * The app queries it **when it needs the data** — typically **once at startup** (in your entrypoint/init script), and then **again only when it expects an update** (e.g. a periodic check every N minutes, or triggered by some signal).
+  * **"Constant polling"** in the sense of a tight ''curl'' loop hammering the endpoint many times a second — **not** needed.
-  * It is //not// required to be a tight ''curl'' loop. You pull, you get the current artifacts, you write them to disk / apply them, done.
+  * **"Polling at all"** — this **is** required if you want the app to notice a change on its own. EVE will not tell it.
+So the accurate statement is: **yes, the app must poll** — you just choose the interval
+(every 30 s, every 5 min, whatever your freshness tolerance is), and you compare **SHA
+hashes** to avoid re-applying unchanged blobs. It is still polling; it is just cheap polling.
+The only way to avoid polling entirely is to **not have the app auto-discover updates** —
+i.e. only fetch on startup, and force a re-fetch by some external action (redeploy/restart
+the instance, or bump the app so its entrypoint runs again). That is not the app "noticing"
+a new config — that is you pushing a lifecycle event.
+==== Bottom line for your design ====
+  * Want the running app to pick up config changes on its own → **it must poll** (''description.json'', SHA-compare, re-download on change). Pick a sane interval.
+  * Don't want polling → fetch once at boot only, and treat any config change as "restart/redeploy the instance."
+There is **no server-push option** in the current patch-envelope design.
 ==== Metadata endpoints ====
@@ Line 42: / Line 92: @@
 > instance (the same ''169.254.169.254'' link-local service used for cloud-init/ECO metadata).
 > An app on a pure switch NI with no local-NI path will not see it.
+==== ⚠ Gotcha — reachability of 169.254.169.254 ====
+The metadata service **lives inside EVE** on the edge node — it is **not** exposed outside the
+node. This has direct consequences for how the workload is networked:
+  * **Local-type NI can reach it; Switch-type cannot.** A **Local** network instance routes to ''169.254.169.254''. A **Switch** NI is pure **layer 2** (a bridge to the physical LAN) and has no path to an address that only exists inside EVE. So the app **must** have an interface on a **Local** NI to hit the metadata service.
+  * **Multi-NIC default-route trap.** If a workload is attached to **two** network instances (e.g. one Local + one Switch, or two with default routes) and **both provide a default gateway**, the guest may pick the **Switch** interface as its default route — and then traffic to ''169.254.169.254'' goes out the wrong interface and **fails**.
+  * **Fix — configure it on the Local network instance, NOT inside the guest.** EVE hands routes to the app through the **Local NI configuration** (advertised to the attached app via the NI's DHCP), not via manual ''ip route'' commands. Add a **static route** for the metadata address on the Local NI so the app always routes metadata traffic via that interface regardless of which one holds the default route. In the ''zedcloud_network_instance'' resource this is the ''static_routes'' block: <code>static_routes {
+  prefix  = "169.254.169.254/32"
+  gateway = "<Local NI gateway IP>"
+}</code> (The NI also has ''propagate_connected_routes'' for auto-propagating its connected routes.)
 **How to detect changes without busy-polling:** fetch ''description.json'' and compare the
@@ Line 52: / Line 114: @@
   - **Inline artifacts (≤ 10 KB)** — carried inside the EdgeDevConfig itself and served directly by the metadata server. Good for small configs.
-  - **External artifacts** — represented as **volumes**, pulled by EVE's volume manager from a configured **datastore**, and referenced via ''VolumeRefs'' in ''description.json''. Use this for larger blobs. These inherit the **datastore's ACL/access requirements**, so the datastore must be reachable and permissioned correctly.
+  - **External artifacts** — represented as **volumes**, pulled by EVE's volume manager from a configured **datastore**, and referenced via ''VolumeRefs'' in ''description.json''. Use this for larger blobs (binaries, ''.exe'', tarballs, datasets). These inherit the **datastore's ACL/access requirements**, so the datastore must be reachable and permissioned correctly.
 ===== Practical takeaway =====