====== ZEDEDA Platform Workshop: EVE-OS and EVE-KVM Workflows ======

This wiki covers the core ZEDEDA Cloud objects and workflows used to deploy and manage edge workloads on EVE-KVM. Each section explains what the object is, how to create it via ZEDUI, Terraform, and the API, and what happens on the edge node when it is applied.

===== Sections =====

^ # ^ Page ^ Description ^
| 01 | [[01_projects|Projects]] | Top-level org unit; types, policies, Zero-Touch Deployments |
| 02 | [[02_datastores|Datastores]] | Remote storage backends: HTTP, S3, Azure Blob, container registries |
| 03 | [[03_images|Images]] | VM disk images and OCI container images |
| 03a | [[03a_networks|Networks]] | EVE-OS control-plane port config: DHCP, static IP, proxy |
| 03b | [[03b_network_instances|Network Instances]] | App data-plane networking: Switch and Local NIs |
| 04 | [[04_eve_os_images|EVE-OS Images]] | OS firmware for edge nodes; upgrades, variants, cluster upgrades |
| 05 | [[05_patch_envelopes|Patch Envelopes]] | Runtime file and config delivery to running apps via metadata server |
| 06 | [[06_persistent_volumes_and_content_trees|Persistent Volumes and Content Trees]] | Stateful block storage and read-only image-backed volumes |
| 07a | [[07a_edge_apps|Edge Apps]] | App Bundle definitions: manifest, images, interfaces, ACLs, resources |
| 07b | [[07b_app_instances|App Instances]] | Deploying bundles to nodes: network wiring, cloud-init, SR-IOV |
| 08 | [[08_deploying_from_marketplace|Marketplace]] | Importing and deploying Marketplace apps (same flow as App Instances) |

===== Dependency and Creation Order =====

When setting up a project from scratch, create objects in this order:

  - **Project** -- everything else belongs to it
  - **Datastores** -- required before Images and Content Trees
  - **Networks** -- required before edge nodes can connect (control plane)
  - **Images** -- required before App Bundles
  - **EVE-OS Images** -- assign to edge nodes during or after onboarding
  - **Network Instances** -- required before App Instances (data plane)
  - **Persistent Volumes / Content Trees** -- create before or alongside App Instances
  - **Patch Envelopes** -- create before or after App Bundles as needed
  - **App Bundle** -- references images, declares interface names, resources, ACLs
  - **App Instance** -- deploys the bundle to a node; wires interfaces to Network Instances

===== Architecture: How It All Flows =====

  ZEDUI / Terraform / API
          |
          v
  ZEDEDA Cloud Controller
  (stores config, tracks state,
   distributes to devices)
          |
          | HTTPS / mTLS heartbeat (default 60s)
          |
          v
  EVE-OS on Edge Node
  (pulls config, downloads images from datastores,
   creates network instances, starts workloads via KVM)
          |
          v
  Running Workload
  (VM via KVM/QEMU on EVE-KVM,
   or OCI container via containerd)

===== Key Concepts =====

  * **Heartbeat**: EVE-OS checks in with the controller on a regular interval (default 60 seconds). Config changes are delivered at the next heartbeat, not pushed in real time.
  * **Measured Boot**: EVE-OS uses TPM-based measured boot to record component state for remote attestation. Not the same as secure boot -- measured boot records and reports state; it does not block unsigned code.
  * **A/B Partitions**: EVE-OS updates use a dual-partition scheme. Updates are written to the inactive partition and activated on reboot. The previous partition is kept as a fallback.
  * **Network vs Network Instance**: A Network configures how a physical port gets its IP (EVE control plane). A Network Instance is a virtual network for app workloads (app data plane).
  * **Switch NI vs Local NI**: Switch NI is a transparent L2 bridge -- apps are on the physical wire. Local NI is a virtual router with EVE-OS running DHCP and NAT.
  * **App Bundle vs App Instance**: The bundle is the definition (what to run). The instance is the deployment (where to run it, how to wire it).
  * **Project Scoping**: All objects belong to a project. API tokens and users are permissioned at the project level.