Spiral Discovery: Expanding Topology Layer by Layer from a Single Entry Point

Overview

In real-world environments, the assets you need to manage are rarely a "blank slate." The more common starting point is a single known entry point: a vCenter, a Kubernetes cluster, or a core switch. Starting from this one entry point, the platform can automatically discover the entire topology behind it — virtual machines, hypervisors, container nodes, neighboring network devices — and automatically turn these newly discovered objects into fully configured collection points. Those collection points, in turn, discover information at an even deeper layer.

This layer-by-layer expansion — discover a batch → auto-onboard → discover more → onboard again — is the platform's Spiral Discovery. It is the most effortless combination between Discovery & Collection and CMDB: you manually configure just one entry point, and templates and discovery rules take care of the rest automatically.

In one sentence

Starting from a single vCenter entry point, within minutes a complete topology of "Data Center → Cluster → ESXi → Virtual Machine" automatically grows in CMDB. Each VM automatically becomes a collection point and begins returning detailed OS / hardware / installed software information — all without configuring each machine individually.

Prerequisite Reading

This guide combines multiple modules. Before reading, we recommend familiarizing yourself with:

• Discovery & Collection Overview — the overall concept of Discovery & Collection
• Collection Points and Collection Point Details — what a collection point is and how it connects to devices
• Collection Templates — the "define once, apply everywhere" power of templates
• Collection Rules — the auto-onboard rules that define "what to do automatically after finding a device"

Why "Spiral": Two Pipelines, One Template

The key to understanding spiral discovery is recognizing that inside every "by API" template, two independent pipelines run in parallel. They cooperate but do not overlap:

Pipeline	Corresponding Discovery Item	Output	Lands In
① CI Discovery	*.ci.discovery	Configuration Items (CIs) + relationships	CMDB (topology graph)
② Collection Point Discovery Rule	*.vm.discovery / *.node.discovery / snmp.neighbor.discovery	Identifiers of child objects (IP / UUID / OS type)	Auto-creates collection points + binds templates

• CI Discovery is solely responsible for "painting the topology into CMDB": it discovers CIs such as VMs, hypervisors, and switches, and builds their membership / connection relationships — but it does not create collection points.
• Collection Point Discovery Rules are solely responsible for "turning child objects into managed collection points": they return each child object's IP / UUID and other identifiers. The server then uses a host prototype to automatically create collection points and auto-binds the corresponding collection template through the template link attached to the host prototype.

After the newly created collection points come online, the templates bound to them often carry their own CI discovery items — triggering another round of deeper discovery (OS, hardware, installed software...). This constitutes the "second turn" of the spiral.

Host Prototypes Are the "Engine" of the Spiral

The "auto-create collection points + bind templates" mechanism is driven by host prototypes within the template. A host prototype predefines "when a child object matching certain criteria is discovered (by OS, by IP rules) → create a collection point → attach which templates." You typically do not need to write host prototypes yourself — the platform's built-in templates already include them.

Scenario 1: VMware Topology Discovery and Auto-Onboard

This is the most classic spiral scenario. The goal: given a vCenter, automatically obtain the complete virtualization topology and onboard every VM as a collection point.

What You Need to Do

You only need to manually configure one top-level collection point:

1. Create a new collection point named vCenter, associate the built-in template VMware by API, select a group, and initially disable the collection point.
2. Configure the connection authentication information (both locations must be filled in):
   • In that collection point's macros, fill in the vCenter connection credentials (see the VMware row in Required Fields Quick Reference).
   • Open the host prototypes under the vCenter's collection point discovery rule VMware VM discovery, and in each prototype's respective macros, fill in the connection credentials that the prototype requires (see the "Auto-created collection points" section in Credential Configuration).
3. Enable the collection point.

Let the two pipelines inside the template handle the rest automatically.

What Happens Automatically

• First turn: vmware.ci.discovery traverses the vCenter top-down, writing CIs such as vCenter, data centers, clusters, ESXi hypervisors, VMs, storage, and resource pools — along with their hierarchical relationships — into CMDB. Your virtualization topology graph is generated automatically.
• Creating collection points: vmware.vm.discovery outputs identifiers such as IP / UUID / guest OS for each VM. The server matches host prototypes by OS type and automatically creates a collection point for each VM.
• Auto-binding templates: Linux VMs are automatically bound to Linux and macOS by SSH; Windows VMs are automatically bound to Windows by WMI / Windows by PowerShell.
• Second turn: After these new collection points come online, their bound OS templates carry ssh.ci.discovery / wmi.ci.discovery, which writes the internal information of the VMs — hardware, disks, installed software / applications — into CMDB as CIs.

About "Inventory Discovery"

The platform does not have a separate template named "inventory discovery." The "deeper asset information" you want (installed software, application inventory, etc.) is handled by the CI discovery rules within the OS collection templates described above — simply enable the relevant options in the template's CI discovery rules (e.g., Collect installed software / Collect applications) to let the second turn of the spiral return richer inventory data.

Scenario 2: Kubernetes / ZStack / KVM — The Same Pattern

The discovery mechanisms for virtualization / container platforms are structurally identical: the top-level entry point has the corresponding template attached, and the template internally runs the same two pipelines — "CI Discovery + Collection Point Discovery Rule." The only difference is which type of child object gets a collection point created for it.

The configuration steps are the same as the VMware scenario: first create the top-level entry collection point and associate the corresponding template (initially disabled), fill in the connection credentials in the macros per Required Fields Quick Reference and Credential Configuration, and finally enable the collection point.

Top-Level Entry	Associated Template	CI Discovery Writes to CMDB	Objects That Get Auto-Created Collection Points	Auto-Bound Templates
Kubernetes cluster	Kubernetes by API	Cluster / Node / Namespace / Pod / Deployment / Service, etc.	Each Node	Linux and macOS by SSH
ZStack management node	ZStack by HTTP	KVM hypervisors / VMs / Storage pools	Each VM	Linux and macOS by SSH / Windows by WMI / Windows by PowerShell
KVM hypervisor	KVM with libvirt by SSH	Hypervisors / VMs	Each VM	Linux and macOS by SSH / Windows by WMI / Windows by PowerShell

Note the Kubernetes Boundary

Kubernetes discovery rules only create collection points for Nodes. Objects such as Pods, Services, and Containers enter CMDB as CIs (for topology and relationships) but do not each become collection points — they are too numerous and short-lived to manage individually. When you need to perform SSH collection on a node, the platform has already automatically created a collection point for each Node.

Scenario 3: Network Neighbor Spiral (CDP / LLDP / ARP / MAC)

The network-side spiral is even more pure: a single core switch with SNMP enabled can lead you to discover an entire network. Note: the spiral can only continue to fan outward through SNMP-enabled devices, creating new collection points and CIs.

Configuration steps: create a collection point for the core switch, associate the built-in template Network Discovery by SNMP (initially disabled), fill in the SNMP credentials in the macros ({$SNMP_COMMUNITY} or SNMPv3 parameters, see Required Fields Quick Reference), and finally enable the collection point. Auto-created neighbor collection points reuse the top-level entry's SNMP credentials — no need to configure each one individually.

• Associate the built-in template Network Discovery by SNMP with a collection point on a known switch.
• snmp.neighbor.discovery discovers neighboring devices of this switch through four sources: ARP tables, MAC address tables (FDB), CDP, and LLDP.
• Each neighbor with an IP address automatically gets a collection point created via a host prototype, and is bound back to the Network Discovery by SNMP template itself.
• Because the new collection point carries the same template, on the next cycle it runs snmp.neighbor.discovery to discover its neighbors — expanding outward layer by layer until the entire reachable network is converged.

This is the true "self-recursive" spiral on the network side: the template binds back to itself, extending outward hop by hop through periodic re-scans.

UI Configuration Essentials: What Every Scenario Requires

The spiral can only spin if the top-level entry collection point is configured correctly. The collection point configuration form has three sections (see Collection Point Details — Create a Collection Point):

Section	What to Fill In	Role in the Spiral
Overview	Name, Interface (address / port / protocol), Proxy, Associated Templates, Group, Status	Associated Templates = select the by API template; Group = categorize this entry point
Tags	(Optional) key-value tag pairs	Labeling / filtering
Macros	Connection variables declared by the template (one independent macro per item, e.g., {$VMWARE.URL}, {$KUBE.API.TOKEN})	Where you fill in the API address, username, password / Token — different protocols use different macro names, see the table below

by API Scenarios: Address and Credentials Go in "Macros", Not the Interface Fields

For by API entry points such as VMware / Kubernetes / ZStack, the actual API address (e.g., vCenter SDK URL, k8s API Server) and credentials / Token are all filled in the Macros section. The Interface field holds the management address and port (used to determine whether the collection point is reachable). Only direct collection (Agent / SNMP / SSH / WMI) puts address credentials primarily in the interface.

Required Fields Quick Reference

Scenario	Associated Template (Overview)	Interface (Overview)	Required Macros (Top-Level Entry · Macros Section)	Group (Overview)
VMware	VMware by API	vCenter address · 443	{$VMWARE.URL} · {$VMWARE.USERNAME} · {$VMWARE.PASSWORD}	e.g., "Virtualization"
Kubernetes	Kubernetes by API	API Server address · 6443	{$KUBE.API.URL} · {$KUBE.API.TOKEN} (for self-signed certs, leave {$KUBE.VERIFY_TLS} at its default false — no change needed)	e.g., "Container"
ZStack	ZStack by HTTP	Management address · actual port	{$KVM.API.URL} · {$KVM.API.USERNAME} · {$KVM.API.PASSWORD}	e.g., "Virtualization"
KVM	KVM with libvirt by SSH	Hypervisor address · 22	{$SSH.USERNAME} · {$SSH.PASSWORD} (or public key) · {$KVM.SUDO_PASSWORD}	e.g., "Virtualization"
Network Neighbor	Network Discovery by SNMP	Device address · 161	{$SNMP_COMMUNITY} (SNMPv2c) or SNMPv3 credentials	e.g., "Network Devices"

When to change the port

When a device uses a non-default port, change it in the Interface: SSH defaults to 22, SNMP to 161, HTTPS to 443, WinRM to 5985 (HTTP) / 5986 (HTTPS), k8s API to 6443. For example, if SSH is moved to 2222 or SNMP to 1161, enter the new value in the interface port.

Credential Configuration

There are two types of collection points in the spiral, and credentials live in different places — this is the most commonly misconfigured aspect:

Collection Point	Who Creates It	Where Credentials Are Configured
Top-level entry collection point (vCenter / k8s / core switch — only 1)	You create it manually	That collection point's own Macros section (i.e., the required macros in the table above)
Auto-created collection points (VMs / nodes / neighbors — potentially hundreds)	Automatically generated by the collection point discovery rule + host prototype in the template bound to the entry collection point	The host prototype under that discovery rule — fill in macros like {$SSH.USERNAME} on the prototype, and every auto-created point inherits them

You manually create only the single top-level entry, and its connection macros go in its own macros section. The VMs / nodes and other auto-created collection points can number in the hundreds or thousands — it's impossible to fill them in one by one. So their credentials are configured on the host prototype — when the prototype generates a collection point, it carries the credentials along. For example, in the VMware template's "Linux VM" prototype, fill in {$SSH.USERNAME} / {$SSH.PASSWORD}, and every subsequently auto-onboarded Linux VM comes with this SSH credential set.

Do Not Hardcode Credential Values in Templates

Templates only declare / reference which macros they need (e.g., the "Linux and macOS by SSH" template references {$SSH.USERNAME} / {$SSH.PASSWORD}). What is hardcoded in templates is the collection item configuration itself (keys, OIDs, collection intervals). Credential values should never be written as default values in templates — once a template like that is reused, credentials spread everywhere it is applied, which is both insecure and unmaintainable. Credential values belong uniformly in host prototypes (for auto-created point scenarios) or in the top-level entry's macros.

Spiral Boundaries and Troubleshooting

Understanding the following boundaries helps avoid misjudging spiral behavior:

• There is no "recursion depth" parameter. The spiral's layer-by-layer expansion is not a recursive algorithm but rather template hierarchy composition + periodic re-scan convergence: host prototypes naturally produce only one layer (an OS template does not go back and discover the hypervisor), and network neighbors converge outward gradually with each discovery cycle. This means the topology is progressively complete — newly connected devices typically need to wait one or two discovery cycles to fully populate in CMDB.
• Objects without an IP do not become collection points. If a VM has not obtained an IP or a neighbor device has no IP, the discovery rule filters them out (a collection point requires an IP). These objects may still enter CMDB as CIs but will not be auto-onboarded.
• Neighbor relationships converge gradually. The Connected relationship between neighbors is only established after both sides have become CIs. When only one side has been discovered, the relationship is temporarily absent — this is normal and will be filled in on the next cycle.
• Insufficient credential permissions are the #1 cause of silent failures. CI discovery often "connects but cannot read everything" — for example, a vCenter account lacking data center permissions, or a k8s token missing a ClusterRole binding. The symptom is an incomplete topology or some VMs not getting collection points. When troubleshooting, start with the entry collection point's macros (credentials) and account permissions.
• Do not modify the built-in template's discovery items. The spiral depends on the pairing between CI discovery items and collection point discovery rule items within the template. If you need customization, prefer using Collection Rules to append actions (tagging, grouping) during auto-onboard, rather than modifying the built-in template itself.

Summary

The power of spiral discovery lies in transforming "manual one-by-one onboarding" into "configure one entry point and wait for the topology to grow itself." Its core comes down to two sentences:

• CI Discovery paints the topology into CMDB.
• Collection Point Discovery Rules + Host Prototypes automatically turn child objects into collection points with bound templates, and the new collection points trigger a deeper round of CI discovery.

Keep this mental model of "two pipelines, one template" in mind, and scenarios like VMware / Kubernetes / ZStack / KVM / Network Neighbor are all variations of the same pattern.