Table of Contents

ZEDEDA Tags: UI, API, and Terraform

Tags in ZEDEDA Cloud are name/value pairs used to categorize resources and to target groups of edge nodes, for example location:us-west. They serve two distinct jobs: plain categorization/filtering of objects, and selection/matching that drives automation (Zero-Touch Deployments, cluster node pools, network-instance selection). The same word “tag” is reused for several mechanisms that behave differently, so the taxonomy below is worth reading before the per-surface detail.

Tag constraints

These limits are identical across the UI, the API, and the Terraform provider:

Tag taxonomy (do not conflate these)

Concept What it is Used for ZCLI flag / TF field
Object tags key:value map on an object Categorization, filtering, ZTD matching –tags / tags
Adapter labels (shared labels) free-form string(s) on a network port Group ports so a network instance can select a port group instead of one named port sharedLabels (per-port)
Port tags key:value map on a port Categorize/select ports port_tags (TF, network instance)
Network tag key:value used to associate a node with networks Select/associate networks at node create/update –network-tag
Edge-node-pool tag key:value used to pick which nodes form a K3s cluster pool Cluster membership selection –edge-node-pool-tag
Deployment tag key:value on a deployment version, matched to node tags ZTD: pick which deployment version applies to a node –deployment-tag / “Deployment Tag Name”

The most important split: object tags are metadata you attach to a thing, while adapter labels, network tags, pool tags, and deployment tags are selectors that ZEDEDA evaluates to decide what gets wired up or deployed where.

Tags in the UI

Where you set object tags

You are prompted to enter Tags during creation of, and can edit them on, these objects:

In the GUI a tag is entered as a key field plus a value field, then committed with the plus (+) sign, e.g. key location, value us-west.

Zero-Touch Deployments (the main reason object tags matter)

ZTD is the automation built on tagging plus projects. The mechanics, as documented:

Versioning and rollback ride on the same mechanism:

Note: the public documentation states that node tags are “matched” to application/deployment tags but does not spell out the exact boolean semantics (whether a node must carry all of an application's tags, a subset, or exactly one). Treat the match as tag-based association scoped to a project and confirm the precise operator against controller behavior before relying on subset/superset assumptions.

Cluster and network-instance selection by tag

Switch NI tag → cluster network

For non-clustered - EVE-KVM based edge nodes

Adapter label → network instance → VM (EVE-KVM)

Tags in the API

The public API exposes object tags as a tags map on the relevant object schemas, with the same name/value constraints listed above. The Terraform provider's resource schemas are generated to match the API schemas, so the field names below map directly onto the API.

ZCLI, which sits on the same API, exposes tags as repeatable key:value flags: 

zcli edge-node create <name> --project=<project> --model=<model> \
  [--tags=<key:value>...] \
  [--network-tag=<key:value>...] \
  [--deployment-tag=<deployment-tag>] \
  [--activate]

zcli edge-node update <name> [--tags=<key:value>...] [--network-tag=<key:value>...] [--deployment-tag=<deployment-tag>]

zcli project update <name> [--tags=<key:value>...]

zcli cluster-instance create <name> --k3s-edge-app=<app> --project=<project> \
  --edge-node-pool-tag=<key:value>... \
  [--network-tag=<key:value>...] \
  [--tags=<key:value>...]

A concrete cluster-instance example from the docs: 

zcli cluster-instance create test_instance --k3s-edge-app=k3s_on_ubuntu_with_logs \
  --project=adarsh-dev --edge-node-pool-tag=adarsh-k3s:dev2 \
  --cluster-config="/root/cluster-inst.conf" --network-assignment=eth0:default \
  --title="test title" --description="test description" \
  --tags=clusterTagKey:clusterTagValue

Full API endpoint and schema documentation lives at the controller's API docs path (https://zedcontrol.zededa.net/api/v1/docs/), reachable from the in-product API Docs link.

Tags in Terraform

The zededa/zedcloud provider authenticates with a ZEDEDA Cloud API token and exposes tags as an HCL map(string).

Object tags on resources

tags is a Map of String on object resources such as zedcloud_edgenode, zedcloud_network, and zedcloud_network_instance, with the same name/value rules. 

resource "zedcloud_edgenode" "ship_42" {
  name       = "ship-42-node-a"
  title      = "Ship 42 Node A"
  project_id = zedcloud_project.cruise.id
  model_id   = data.zedcloud_model.smc_6029.id

  tags = {
    location  = "us-west"
    vertical  = "cruise"
    role      = "k3s-server"
  }
}

Port tags vs object tags on a network instance

A network instance carries both an object-level tags map and a port_tags map; the latter categorizes/selects ports rather than the instance itself. 

resource "zedcloud_network_instance" "shopfloor" {
  name       = "shopfloor-switch"
  project_id = zedcloud_project.cruise.id
  kind       = "NETWORK_INSTANCE_KIND_SWITCH"

  tags = {
    purpose = "cluster-network"
  }

  port_tags = {
    uplink = "internet-access"
  }
}

Adapter / interface tags on the node

The edge node's network adapter (interface) block also carries a tags map, distinct from the node's top-level tags. In the underlying adapter network config JSON these appear per-port alongside sharedLabels: 

"tags": {},
"sharedLabels": []

Importing existing tagged objects

terraform import zedcloud_edgenode.ship_42 3ab53292-ad51-4807-9ae7-d2882cc3c600

Worked ZTD example

Goal: run app version v2 on the “canary” subset of a project's ships, keep everyone else on v1.

Gotchas

Sources