ZEDEDA WiKi

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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 **name** (key) is case **insensitive**, min length 3, max length 512.
  * Tag **value** is case **sensitive**, min length 3, max length 256.
  * A tag is a single key:value pair; an object carries a map of them.

===== 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:

  * Edge nodes (onboarding flow and Basic Info tab).
  * Projects (Details / Basic Info).
  * Edge applications and edge app policies.
  * Deployments (deployment versions within a Deployment-type project).
  * Network instances.
  * Edge Kubernetes Service clusters and cluster instances.

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:

  * When you onboard a node, add an application, or create a deployment in a project, you assign tags to it.
  * ZEDEDA Cloud matches the tags on edge nodes to the tags on deployments and applications **within the same project**.
  * Matching policies are applied to matching nodes; matching applications are instantiated and deployed on matching nodes.
  * To change what runs on a node, you change the node's tags to match the target application/deployment. The controller reconciles the rest.

Versioning and rollback ride on the same mechanism:

  * Existing deployments are immutable; you create new **versions** instead. A project retains up to 100 of its most recent deployments.
  * To roll a node back (or forward) to a specific version, edit the node's **Deployment Tag Name** (Edge Node > Basic Info > pencil) to match the tag of the desired deployment version.

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 ====

  * When adding nodes to an Edge Kubernetes Service cluster in the GUI, you supply existing **Edge Node Tags** and existing **Edge Node Network Adapter Tags** to pick the nodes and the adapters used for cluster routing.
  * For the cluster network, choosing **Tag** (instead of Default) means you specify a tag that must match the tag used when creating the switch network instances on the nodes. Network instances carrying that tag are picked up on all cluster nodes to form the cluster network.

{{ :zededa_cluster_network_by_tag.svg | Switch NI tag → cluster network}}

  * Adapter labels (shared labels) let you assign a free-form string to one or more ports so a network instance can target a group of ports; a port can carry multiple labels and belong to multiple groups.

**For non-clustered - EVE-KVM based edge nodes**

{{ :zededa_ni_tag_evekvm.svg |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:

<code>
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>...]
</code>

A concrete cluster-instance example from the docs:

<code>
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
</code>

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.

<code>
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"
  }
}
</code>

==== 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.

<code>
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"
  }
}
</code>

==== 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'':

<code>
"tags": {},
"sharedLabels": []
</code>

==== Importing existing tagged objects ====

<code>
terraform import zedcloud_edgenode.ship_42 3ab53292-ad51-4807-9ae7-d2882cc3c600
</code>

===== Worked ZTD example =====

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

  * Tag the canary nodes ''release:canary'' and the rest ''release:stable''.
  * Create deployment version that targets ''release:canary'' with the v2 application/policy set, and a version targeting ''release:stable'' with v1.
  * The controller deploys v2 to canary nodes and v1 to stable nodes, all within the one project.
  * To promote: change a node's ''release'' value (or its Deployment Tag Name) from ''canary'' to ''stable'' once v2 is validated, or point the stable deployment at the v2 set.
  * To roll back a node: set its Deployment Tag Name to the tag of the earlier stored version.

===== Gotchas =====

  * ''type = "TAG_TYPE_PROJECT"'' on the ''zedcloud_project'' resource is the project/object **class** enum, not a tag you are applying. It is an unfortunate naming overlap; it has nothing to do with object tags.
  * Object tags (''tags'') and selectors (''network-tag'', ''edge-node-pool-tag'', deployment tag, adapter labels) are different fields with different effects, even though all are called "tags" colloquially.
  * Tag **names** are case-insensitive but **values** are case-sensitive, so ''us-west'' and ''US-West'' are different values under the same key.
  * Minimum length is 3 for both key and value, which rules out short codes like ''hq'' or numeric ''1''.
  * Cluster network selection by Tag requires the network-instance tag to match exactly the tag used when the switch NIs were created on the nodes.
  * Deployments are immutable and versioned (max 100 retained per project); you re-target nodes by changing tags, not by editing a deployment in place.

===== Sources =====

  * [[https://help.zededa.com/hc/en-us/articles/27953925647899-Onboard-an-edge-node-to-ZEDEDA-Cloud|Onboard an edge node (tag definition, name/value limits, adapter labels)]]
  * [[https://help.zededa.com/hc/en-us/articles/17078162009627-Zero-Touch-Deployments-Overview|Zero-Touch Deployments Overview (matching, versioning, rollback)]]
  * [[https://help.zededa.com/hc/en-us/articles/36350180833307-ZCLI-Create-and-Manage-Edge-Nodes|ZCLI: Create and Manage Edge Nodes (--tags, --network-tag, --deployment-tag)]]
  * [[https://help.zededa.com/hc/en-us/articles/35285607938203-Use-the-ZEDEDA-CLI-to-Manage-a-Project|ZCLI: Manage a Project (--tags)]]
  * [[https://help.zededa.com/hc/en-us/articles/4440344903451-Kubernetes-Infrastructure-Orchestration-Operations|K8s Infra Orchestration (cluster-instance --edge-node-pool-tag, NI tag selection)]]
  * [[https://help.zededa.com/hc/en-us/articles/39344203451547-Create-and-Manage-a-ZEDEDA-Edge-Kubernetes-Service-Cluster-Using-the-GUI|EKS cluster GUI (Edge Node Tags, Network Adapter Tags)]]
  * [[https://registry.terraform.io/providers/zededa/zedcloud/latest/docs/resources/edgenode|Terraform zedcloud_edgenode (tags / port_tags map schema)]]
  * [[https://help.zededa.com/hc/en-us/articles/35421906836763-Use-Case-Terraform-for-Edge-Node-Clusters|Terraform for Edge Node Clusters (project type enum)]]
  * [[https://help.zededa.com/hc/en-us/articles/4440359495835-ZEDEDA-Terraform-Provider|ZEDEDA Terraform Provider (auth, import)]]