Differences

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

--- zededa:patch-envelopes [2026/07/21 19:08] – [What is it used for?] mc
+++ zededa:patch-envelopes [2026/07/23 23:24] (current) – mc
@@ Line 7: / Line 7: @@
 the app**. It is a container of one or more **binary artifacts (blobs)**: base64-encoded
 objects that can be anything — a config file, a YAML, certs, a license key, a small binary, etc.
+===== What is it used for? =====
+The core use case is **decoupling mutable data/config from the immutable app image**. Instead
+of baking config into the image (and re-rolling the image every time something changes), you
+attach a patch envelope to the app instance and update //just// that data. Typical scenarios:
+  * 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
+  * Any case where "recreating the image doesn't make sense" or downtime is unacceptable
+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/... ? =====
@@ Line 34: / Line 81: @@
 There is **no server-push option** in the current patch-envelope design.
-===== 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 metadata service at ''169.254.169.254'' is a **pull, on-demand** interface, not a stream
-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).
-  * 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.
 ==== Metadata endpoints ====
@@ Line 55: / 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 65: / 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 =====