Zededa
@dougschaefer/zededav2026.08.04.1
01README
Manage a ZEDEDA Cloud (ZEDCloud) tenant and the EVE-OS edge nodes it controls, over the ZEDCloud REST API. Bearer auth with a vault-resolved session token, plus a two-step token-exchange method for rotating it before its 90-day expiry. Read controller and tenant status, sweep the whole object graph in one fan-out inventory call, list and inspect edge nodes with fleet-wide health rollup, and read app instances, logs, events, and time-series metrics. Onboard nodes zero-touch by minting a single-use EVE-OS installer bound to one node, drive node lifecycle (activate, deactivate, reboot, prepare-power-off, offboard), open EdgeView remote-access sessions, run EVE-OS base image upgrades, deploy and control application instances, create node-local network instances, and reach any other endpoint through a generic authenticated passthrough.
02Release Notes
Add createDatastore and createImage, the two declarations an edge app needs before it can reference an artifact. ZEDCloud never discovers datastore contents on its own, so every blob, object, or registry tag has to be registered explicitly. Datastore credentials go in nested under the secret object, come back encrypted, are stripped from the stored resource, and are redacted from ZEDCloud parse errors, which echo the offending request fragment. The apiPasswd argument is marked sensitive so swamp keeps it out of run output.
03Models
@dougschaefer/zededav2026.08.04.1zededa/zededa.ts
fn getSession()
Read the current session — who the configured token authenticates as, and which enterprise it is scoped to. Cheapest check that a token is still valid.
fn mintSessionToken(expiresSeconds: number)
Perform the two-step ZEDCloud token exchange (login, then session token) using the vault-resolved username and password. ZEDCloud session tokens expire — 90 days by default — so this is the rotation path. The token VALUE IS NOT WRITTEN to the data model: swamp resources are stored in the clear, and extensions cannot write to vault, so only expiry and a fingerprint are recorded. Read the value from this method's log-free return by rotating it manually into vault.
| Argument | Type | Description |
|---|---|---|
| expiresSeconds | number | Requested token lifetime in seconds; defaults to the tenant's configured expiry (90 days) |
fn getStatus()
Report controller version, tenant identity, and top-level object counts. Read-only health check — run this first to prove the API token works.
fn inventory(kinds: array, pageSize: number, projectName: string)
Fan-out sweep of the whole tenant: fetches projects, hardware models and brands, edge nodes, edge apps, app instances, images, datastores, volume instances, networks, and network instances in one run, writing one collection per kind.
| Argument | Type | Description |
|---|---|---|
| kinds | array | Object kinds to sweep. Defaults to every kind. |
| pageSize | number | Rows requested per kind |
| projectName | string | Optional: restrict node/app/network results to one project |
fn listNodes(namePattern: string, projectName: string, adminState: enum, pageSize: number, pageNum: number)
List edge nodes (ZEDNodes) with optional name, project, cluster, and admin-state filters.
| Argument | Type | Description |
|---|---|---|
| namePattern | string | Filter by node name pattern |
| projectName | string | Filter by project name |
| adminState | enum | Filter by admin state |
| pageSize | number | Rows per page |
| pageNum | number | 1-based page number |
fn getNode(id: string, name: string, serialNo: string)
Fetch one edge node's full configuration, addressed by id, name, or hardware serial number.
| Argument | Type | Description |
|---|---|---|
| id | string | Node id |
| name | string | Node name |
| serialNo | string | Hardware serial number |
fn getNodeStatus(id: string, name: string, serialNo: string)
Fetch one edge node's runtime status and hardware/software info (run state, EVE-OS version, interfaces, storage).
| Argument | Type | Description |
|---|---|---|
| id | string | Node id |
| name | string | Node name |
| serialNo | string | Hardware serial number |
fn fleetHealth(projectName: string, pageSize: number)
One-shot health sweep across every edge node: queries the node status collection and rolls up online/offline counts and EVE-OS version distribution. Use this instead of looping getNodeStatus.
| Argument | Type | Description |
|---|---|---|
| projectName | string | Optional: restrict to one project |
| pageSize | number | Nodes fetched per page |
fn getNodeEvents(id: string, name: string, pageSize: number)
Fetch the event timeline for one edge node (onboarding, reboots, config pushes, errors).
| Argument | Type | Description |
|---|---|---|
| id | string | Node id |
| name | string | Node name |
| pageSize | number | Events per page |
fn getNodeMetrics(id: string, name: string, metricType: enum, startTime: string, endTime: string)
Fetch a time-series metric window for one edge node (CPU, memory, network, storage, or event counts).
| Argument | Type | Description |
|---|---|---|
| id | string | Node id |
| name | string | Node name |
| metricType | enum | Metric family to fetch |
| startTime | string | RFC3339 window start, e.g. 2026-07-30T00:00:00Z |
| endTime | string | RFC3339 window end |
fn listAppInstances(namePattern: string, projectName: string, pageSize: number)
List application instances (VMs and containers running on edge nodes), optionally filtered by name or project.
| Argument | Type | Description |
|---|---|---|
| namePattern | string | Filter by instance name |
| projectName | string | Filter by project name |
| pageSize | number | Rows per page |
fn getAppInstanceStatus(id: string, name: string)
Fetch runtime status for one application instance (run state, resource use, attached networks and volumes).
| Argument | Type | Description |
|---|---|---|
| id | string | App instance id |
| name | string | App instance name |
fn getAppInstanceLogs(id: string, pageSize: number)
Fetch recent console/application logs for one application instance.
| Argument | Type | Description |
|---|---|---|
| id | string | App instance id |
| pageSize | number | Log lines per page |
fn createNode(name: string, title: string, projectId: string, modelId: string, serialNo: string, description: string, adminState: enum, tags: record)
Register a new edge node in ZEDCloud ahead of hardware arriving. Requires a project and hardware model; supply the serial number for automatic onboarding, or omit it and use createSingleUseImage instead.
| Argument | Type | Description |
|---|---|---|
| name | string | Node name, unique within the tenant |
| title | string | Human-readable title |
| projectId | string | Project (resource group) id |
| modelId | string | Hardware model id — see inventory kind hardwareModels |
| serialNo | string | Hardware serial number; enables serial-based zero-touch onboarding |
| description | string | Free-text description |
| adminState | enum | Initial admin state; activate separately with setNodeState |
| tags | record | Key/value tags applied to the node |
fn getNodeOnboarding(id: string, name: string)
Fetch the onboarding record for a node — onboarding key, serial, and certificate state. Use this to confirm a node is ready to claim before shipping hardware.
| Argument | Type | Description |
|---|---|---|
| id | string | Node id |
| name | string | Node name |
fn createSingleUseImage(id: string, name: string, eveImageName: string)
Mint a single-use EVE-OS installer image bound to one registered node, and return its download link. This is the zero-touch path: flash the image, boot the hardware, and it claims itself against this node with no console work on site.
| Argument | Type | Description |
|---|---|---|
| id | string | Node id |
| name | string | Node name |
| eveImageName | string | Optional EVE-OS base image name to bake in; defaults to the tenant's latest |
fn setNodeState(id: string, name: string, action: enum)
Apply a lifecycle transition to an edge node: activate, deactivate, reboot, preparePowerOff, or offboard.
| Argument | Type | Description |
|---|---|---|
| id | string | Node id |
| name | string | Node name |
| action | enum | Transition to apply |
fn setEdgeview(id: string, name: string, enabled: boolean, fetchClientScript: boolean)
Enable or disable EdgeView on a node — the dial-out remote-access session ZEDEDA uses instead of inbound ports — and fetch the client script needed to connect.
| Argument | Type | Description |
|---|---|---|
| id | string | Node id |
| name | string | Node name |
| enabled | boolean | true to start an EdgeView session, false to stop it |
| fetchClientScript | boolean | When enabling, also fetch the EdgeView client script |
fn upgradeNodeBaseOs(id: string, name: string, baseImageName: string, forceUpgrade: boolean)
Set the EVE-OS base image on a node and publish the change, driving an in-place EVE-OS upgrade on next check-in.
| Argument | Type | Description |
|---|---|---|
| id | string | Node id |
| name | string | Node name |
| baseImageName | string | EVE-OS base image name to apply — see inventory kind images |
| forceUpgrade | boolean | Bypass the controller's upgrade eligibility checks |
fn createAppInstance(name: string, title: string, deviceId: string, appId: string, projectId: string, activate: boolean, interfaces: array, customConfig: record)
Deploy an application instance (VM or container) onto an edge node from an existing edge app bundle.
| Argument | Type | Description |
|---|---|---|
| name | string | Instance name, unique within the tenant |
| title | string | Human-readable title |
| deviceId | string | Edge node id to deploy onto |
| appId | string | Edge app bundle id |
| projectId | string | Project id |
| activate | boolean | Start the instance immediately after creation |
| interfaces | array | Network interface bindings, e.g. [{ intfname: 'eth0', netinstname: 'lab-local' }] |
| customConfig | record | Optional cloud-init / custom config block passed through verbatim |
fn setAppInstanceState(id: string, action: enum)
Apply a lifecycle transition to an application instance: activate, deactivate, restart, refresh, or purge.
| Argument | Type | Description |
|---|---|---|
| id | string | App instance id |
| action | enum | Transition to apply |
fn deleteAppInstance(id: string)
Delete an application instance. Verify the target with getAppInstanceStatus first — this removes the workload from the node.
| Argument | Type | Description |
|---|---|---|
| id | string | App instance id |
fn createNetworkInstance(name: string, title: string, deviceId: string, kind: enum, port: string, projectId: string, dhcpSubnet: string)
Create a network instance on an edge node — the node-local network (local NAT, switch/bridge, or cloud) that application instances attach to.
| Argument | Type | Description |
|---|---|---|
| name | string | Network instance name |
| title | string | Human-readable title |
| deviceId | string | Edge node id to create it on |
| kind | enum | Local = NAT behind the node; Switch = bridged to the LAN; Cloud = tunnelled |
| port | string | Node port or port label to bind to, e.g. uplink or eth0 |
| projectId | string | Project id |
| dhcpSubnet | string | Optional subnet for the built-in DHCP server, e.g. 10.10.1.0/24 |
fn createDatastore(name: string, title: string, dsType: enum, dsFQDN: string, dsPath: string, region: string, apiKey: string, apiPasswd: string)
Register an image datastore — the bucket, container, or registry ZEDCloud pulls edge-app images from. Credentials go in as apiKey/apiPasswd and are encrypted server-side; supply apiPasswd from vault rather than on the command line, and note that nothing secret is written back to the data model.
| Argument | Type | Description |
|---|---|---|
| name | string | Datastore name |
| title | string | Human-readable title; defaults to the name |
| dsType | enum | Backing store kind |
| dsFQDN | string | Endpoint, e.g. https://<account>.blob.core.windows.net or https://index.docker.io |
| dsPath | string | Container, bucket, or repository path within the endpoint |
| region | string | Region, where the backing store needs one (S3). Leave empty for Azure Blob. |
| apiKey | string | Identity half of the credential — the storage account name for Azure Blob, the access key id for S3, the username for a registry. |
| apiPasswd | string | Secret half of the credential — the account key, secret access key, or registry password. Resolve this from vault. |
fn createImage(name: string, title: string, datastoreId: string, imageRelUrl: string, imageFormat: enum, imageArch: enum, imageType: enum, imageSha256: string, imageSizeBytes: string, description: string)
Register one image artifact sitting in a datastore. ZEDCloud does not scan a datastore and discover its contents — every blob, object, or registry tag has to be declared here before an edge app can reference it.
| Argument | Type | Description |
|---|---|---|
| name | string | Image name, unique across the tenant and immutable once created |
| title | string | Human-readable title; defaults to the name |
| datastoreId | string | Datastore id the artifact lives in — see listDatastores or the createDatastore result |
| imageRelUrl | string | Path to the artifact relative to the datastore root, e.g. pexip-node.qcow2 or library/nginx:latest |
| imageFormat | enum | Binary format of the artifact |
| imageArch | enum | Target architecture |
| imageType | enum | Application workload, EVE-OS base image, or one of the runtime/artifact kinds |
| imageSha256 | string | Optional SHA256 checksum; when set, EVE verifies the download against it |
| imageSizeBytes | string | Optional declared size in bytes |
| description | string | Free-text description |
fn apiRequest(method: enum, path: string, query: record, body: record)
Generic authenticated passthrough to any ZEDCloud API path. Use for endpoints without a dedicated method; path is API-relative and begins with /v1 or /v2.
| Argument | Type | Description |
|---|---|---|
| method | enum | HTTP method |
| path | string | API-relative path, e.g. /v1/apps/images/baseos/latest |
| query | record | Query parameters |
| body | record | JSON request body for POST/PUT |
Resources
status(1d)— Controller version and tenant (enterprise) identity
collection(7d)— A list of ZEDCloud objects of one kind (nodes, apps, app instances, images, datastores, volumes, networks, network instances, projects, hardware models, brands)
detail(7d)— Single-object drill-down (node config, node status, app instance status, onboarding record, single-use image)
fleetHealth(30d)— Fleet-wide edge node health: per-node run state, connectivity, and EVE-OS version, with a rollup
metrics(7d)— A time-series metric window for one edge node
mutationResult(90d)— Result of a create, update, delete, or lifecycle transition against ZEDCloud
sessionInfo(90d)— Session/token metadata — expiry, enterprise, and a token fingerprint. Deliberately carries no token value.
apiResult(7d)— Result of a generic authenticated API passthrough call
04Previous Versions
2026.07.30.2
Docs: outcome-first README opening, per the documentation-tier voice sample. No functional change.
2026.07.30.1
First release. Manages a ZEDEDA Cloud (ZEDCloud) tenant and the EVE-OS edge nodes it controls: fan-out inventory and fleet health, zero-touch onboarding via single-use EVE-OS installers, node and app-instance lifecycle, EdgeView remote access, EVE-OS base image upgrades, and network instances. Verified against a live controller.
05Stats
A
100 / 100
Downloads
0
Archive size
35.3 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
06Platforms
07Labels