Differences

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

--- zededa:tagging [2026/08/11 12:14] – mc
+++ zededa:tagging [2026/08/11 12:14] (current) – old revision restored (2026/06/28 20:01) mc
@@ Line 1: / Line 1: @@
-====== Policy deployments, and the tags that drive them ======
+====== ZEDEDA Tags: UI, API, and Terraform ======
-How an edge node gets a whole site — network, storage, apps — without anyone
+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.
-naming that node anywhere.
-===== What a deployment is =====
+===== Tag constraints =====
-A **deployment** is a saved recipe for a site: the network to create, the
+These limits are identical across the UI, the API, and the Terraform provider:
-storage to create, the apps to run. It lives inside a project.
-It never names an edge node. Instead, nodes //qualify// for it. That is the
+  * Tag **name** (key) is case **insensitive**, min length 3, max length 512.
-whole idea: you add a site by tagging hardware, not by editing a deployment
+  * Tag **value** is case **sensitive**, min length 3, max length 256.
-project.
+  * A tag is a single key:value pair; an object carries a map of them.
-**Watch out:** the project holding a deployment must be of type
+===== Tag taxonomy (do not conflate these) =====
-''TAG_TYPE_DEPLOYMENT'' — not the ordinary project type. This is the most
-common setup mistake, and the error message points at the deployment rather
-than the project.
-===== How a node qualifies =====
+^ 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" |
-Two things must line up, and a third wires the app to its network. Each is a
+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.
-pair that must be //equal// on both sides — nothing matches by name.
-==== First, membership ====
+===== Tags in the UI =====
-The edge node has to be moved **into the deployment's project**. A node belongs
+==== Where you set object tags ====
-to exactly one project at a time, so this is a move, not an addition. Nothing
-below is even evaluated until this is true.
-==== Match 1 — picks which deployment ====
+You are prompted to enter Tags during creation of, and can edit them on, these objects:
-^ On the node  ^  ^ On the deployment  ^
+  * Edge nodes (onboarding flow and Basic Info tab).
-| ''deployment_tag = cisco-policy-demo''  | must equal  | ''deployment_tag = cisco-policy-demo''  |
+  * 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.
-A project can hold more than one recipe. This says which one this node gets.
+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''.
-==== Match 2 — picks which policies ====
+==== Zero-Touch Deployments (the main reason object tags matter) ====
-^ On the node — tags  ^  ^ On each policy — target condition  ^
+ZTD is the automation built on tagging plus projects. The mechanics, as documented:
-| ''demo = policy-demo''  | must equal  | ''demo = policy-demo''  |
-One deployment can carry policies for several kinds of site. Each node receives
+  * When you onboard a node, add an application, or create a deployment in a project, you assign tags to it.
-only the ones whose condition its tags satisfy.
+  * 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.
-==== Match 3 — plumbing, never touched in a demo ====
+Versioning and rollback ride on the same mechanism:
-^ On the network policy — tags  ^  ^ On the app's NIC — netinsttag  ^
+  * Existing deployments are immutable; you create new **versions** instead. A project retains up to 100 of its most recent deployments.
-| ''demo = policy-demo-ni''  | must equal  | ''demo = policy-demo-ni''  |
+  * 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.
-The network does not exist until a node qualifies, so the app cannot refer to it
+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.
-by name. It finds it by tag instead.
-**Tip:** matches 2 and 3 both use the key ''demo'' with different values, which
-makes them look related when they are not. Renaming the network tag key to
-something like ''net'' makes it read unambiguously — ''demo='' always means
-nodes, ''net='' always means networks.
-Only matches 1 and 2 are set on the node.
+==== Cluster and network-instance selection by tag ====
-===== What you actually do =====
+  * 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.
-  - Move the node into the project. In ZedControl, change the node's project to the deployment project.
+{{ :zededa_cluster_network_by_tag.svg | Switch NI tag → cluster network}}
-  - Set its deployment tag: ''deployment_tag = cisco-policy-demo''
-  - Set its tags: ''demo = policy-demo''
-That is the entire action. No Terraform run, no touching the node. Within a
+  * 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.
-minute or two the controller creates the network instance and the app instance,
-and the app comes up.
-Instances are named from the project, the app and the device, so two nodes under
+**For non-clustered - EVE-KVM based edge nodes**
-one deployment never collide:
+{{ :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>
-cisco-policy-demo.nginx.TF-CISCO-UCS-130C-M8-32
+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>
-To drain a node, clear its deployment tag. To reset between runs, set it again.
+A concrete cluster-instance example from the docs:
-===== Changing the recipe =====
+<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>
-**A deployment cannot be edited in place.** Terraform will report a successful
+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.
-apply and the controller will keep the old policies. Nothing warns you; the plan
-even goes clean afterwards.
-Any change to a deployment needs a destroy and recreate — and the delete is
+===== Tags in Terraform =====
-refused while a node is still attached, so unbind first:
+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>
-. clear the node's deployment_tag, apply
+resource "zedcloud_edgenode" "ship_42" {
-. terraform apply -replace='...zedcloud_deployment.demo'
+  name       = "ship-42-node-a"
-. set the deployment_tag back, apply
+  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>
-If you edited a deployment and nothing changed on the node, this is almost
+==== Port tags vs object tags on a network instance ====
-always why.
-===== Nothing deployed — what to check =====
+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.
-Every one of these fails //silently//. There is no error to read, so work down
+<code>
-the list.
+resource "zedcloud_network_instance" "shopfloor" {
+  name       = "shopfloor-switch"
+  project_id = zedcloud_project.cruise.id
+  kind       = "NETWORK_INSTANCE_KIND_SWITCH"
-  * Is the project type ''TAG_TYPE_DEPLOYMENT''?
+  tags = {
-  * Is the node in that project — not its old one?
+    purpose = "cluster-network"
-  * Does the node's ''deployment_tag'' match the deployment's, exactly?
+  }
-  * Do the node's tags satisfy every policy's target condition?
-  * Does the controller still hold policies you thought you deleted?
+  port_tags = {
-  * Does the app rely on a default network instance the node does not have?
+    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>
-==== Two red herrings ====
+===== Worked ZTD example =====
-A node reading ''ADMIN_STATE_REGISTERED'' is normal — working nodes read that
+Goal: run app version v2 on the "canary" subset of a project's ships, keep everyone else on v1.
-too. It does not mean the node is inactive.
-Testing a published port //from the node itself// always fails, because traffic
+  * Tag the canary nodes ''release:canary'' and the rest ''release:stable''.
-originating on the host skips the rule that redirects it. Test from another
+  * Create deployment version that targets ''release:canary'' with the v2 application/policy set, and a version targeting ''release:stable'' with v1.
-machine.
+  * 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 =====
-Verified end to end on a Cisco UCS edge node: network instance, volume and nginx
+  * ''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.
-all created by policy, reachable on the node's published port.
+  * 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.
-Terraform reference: ''cisco-ot-ign-demo-policy-based/'' — see
+===== Sources =====
-''README-full.md'' for API queries and the full history.
+  * [[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)]]