Infrastructure node

packs:infrastructure

An infrastructure node is one managed host, hypervisor, network device or link recorded in the estate tree under a project, environment or asset. Nodes are registered one at a time or upserted in batches (an integration feed's natural shape), updated, archived and deregistered rather than deleted — membership closes softly, keeping history. The hot columns ride the row; the long tail of configuration lives in the node's properties document. Served by the v2 InfrastructureService (ListInfrastructureNodes, GetInfrastructureNode, SummarizeInfrastructure, RegisterInfrastructureNode, UpsertInfrastructureNodes, UpdateInfrastructureNode, DeregisterInfrastructureNode); writes are authorised like other node writes, on the parent's infrastructure rule path, 404-on-deny.

InfrastructureNode

InfrastructureNode is one infrastructure node row: the indexed hot columns plus identity. The long tail of configuration lives in the node's properties document, served on the get.

Field	Type	Meaning
address	string	Network address; "" when not recorded. Indexed, unconstrained.
archived	boolean	Shelved but still a member — set and cleared by update.
code	string	The record's code.
created_at	timestamp	When the record was created.
created_by	string	Username of the creating identity.
description	string	"" when never set.
duplicate_address	boolean	True when another non-destroyed infrastructure node in the same environment carries the same address (a warning, never a refusal).
fqdn	string	Fully qualified domain name; "" when not recorded. Indexed, unconstrained.
id	string	The record's identity.
infrastructure_type	string	One of the closed registry: host, hypervisor, network_device, link.
last_facts_at	timestamp	When facts last landed on this node; unset when never.
last_used_at	timestamp	When a run step last reached this node through a transport session (a host_ref-bound step admitted at dispatch); unset when never.
lifecycle_state	string	registered or deregistered (the manual membership states), or one of the reserved integration-asserted states provisioned and destroyed.
name	string	Display name.
node_path	string	The node's own path, e.g. "/projects/web/environments/prod/infrastructure/kvm-mgmt-01".
parent_path	string	The parent node's path (project, environment or asset).
properties_id	string	The node's own properties document id.
settings_id	string	The node's own settings document id.
updated_at	timestamp	When the record was last updated.

InfrastructureFilter

InfrastructureFilter is the typed predicate vocabulary over the indexed hot columns.

Field	Type	Meaning
address	string	Exact address match; "" keeps all.
archived	boolean	Keep only archived (true) or unarchived (false); unset keeps both.
changed_since	timestamp	Keep only rows with a lifecycle-change event (api:infrastructure:provisioned or api:infrastructure:destroyed) at or after this instant — the summary's recently-changed rows; unset keeps all.
code	string	Exact code match; "" keeps all.
duplicate_address	boolean	Keep only rows whose address another same-environment node carries (true) or does not (false); unset keeps both.
fqdn	string	Exact FQDN match; "" keeps all.
include_deregistered	boolean	Include deregistered rows alongside the rest (the soft-close posture hides them by default).
infrastructure_type	string	Keep only one registry type (host, hypervisor, network_device, link); "" keeps all.
last_facts_before	timestamp	Keep only rows whose facts are older than this instant, rows whose facts were never collected included — the summary's stale-facts rows; unset keeps all.
last_used_before	timestamp	Keep only rows no run step has reached since this instant, never-used rows included — the summary's unused rows; unset keeps all.
lifecycle_state	string	Keep only one lifecycle state. "" keeps registered and provisioned; deregistered rows appear only when asked for here or via include_deregistered.
search	string	Case-insensitive substring over name and code; "" keeps all.

InfrastructureSummaryCell

InfrastructureSummaryCell is one count of the infrastructure_type × lifecycle_state matrix under one project, answered by SummarizeInfrastructure; archived rows are counted in their own cells (archived = true) so a matrix can show them apart. Only non-zero cells are served, project path ascending.

Field	Type	Meaning
archived	boolean	Whether this cell counts the archived rows (true) or the unarchived ones (false) of its type and state.
count	integer	How many infrastructure nodes the cell holds.
infrastructure_type	string	One of the closed registry: host, hypervisor, network_device, link.
lifecycle_state	string	registered, deregistered, provisioned or destroyed.
project_path	string	The owning project's path (/projects/<code>); every cell of a project-scoped summary carries the same value.

InfrastructureExceptions

InfrastructureExceptions are the inventory's exception totals over the summarised scope. Every total counts unarchived rows whose membership is open (never deregistered); each maps onto one InfrastructureFilter so a click-through lists exactly the counted rows.

Field	Type	Meaning
destroyed_present	integer	Rows the integration asserted destroyed that were never deregistered (lifecycle_state = destroyed).
duplicate_addresses	integer	Registered or provisioned rows whose address another same-environment node also carries (duplicate_address = true).
recently_changed	integer	Rows with a provisioned or destroyed event within thresholds.recently_changed_within (changed_since = computed_at − recently_changed_within).
stale_facts	integer	Registered or provisioned rows whose facts are older than thresholds.stale_facts_after, or were never collected (last_facts_before = computed_at − stale_facts_after).
unused	integer	Registered or provisioned rows no run step has reached within thresholds.unused_after, never-used rows included (last_used_before = computed_at − unused_after).

InfrastructureSummaryThresholds

InfrastructureSummaryThresholds are the windows the exception totals were judged against — the stored settings infrastructure.stale_facts_after and infrastructure.unused_after (the defaults 168h and 720h when absent or malformed) and the fixed recently-changed window — plus the instant of judgement, so a client can rebuild the matching list filters.

Field	Type	Meaning
computed_at	timestamp	The server's clock when the totals were computed.
recently_changed_within	duration	The recently-changed window (fixed at 7 days).
stale_facts_after	duration	Facts older than this are stale (infrastructure.stale_facts_after).
unused_after	duration	A node not reached within this is unused (infrastructure.unused_after).

InfrastructureUpsertItem

InfrastructureUpsertItem is one batch row: RegisterInfrastructureNode's fields, applied as a create when the code is new under the parent and as an update otherwise.

Field	Type	Meaning
address	string	Network address to record; "" stores none.
code	string	The record's code — the batch's match key under the parent.
description	string	Free-text description.
fqdn	string	Fully qualified domain name to record; "" stores none.
infrastructure_type	string	One of the closed registry: host, hypervisor, network_device, link.
name	string	Display name.
properties_json	string	Replacement properties document as JSON text; "" leaves an existing node's document untouched (and stores an empty one on create).

InfrastructureUpsertResult

InfrastructureUpsertResult is one batch item's outcome.

Field	Type	Meaning
code	string	The record's code.
error	string	The named refusal when outcome is failed; "" otherwise.
node_id	string	The row's node id; "" when the item failed.
outcome	string	created, updated or failed.

Related pages

• opschain docs infrastructure-nodes — the component page: lifecycle, facts, the inventory summary, integration feeds.
• opschain docs settings-reference — the infrastructure.* thresholds behind the summary's exceptions.
• opschain docs packs-infrastructure — the pack whose actions manage these hosts.
• opschain docs resources/properties — the properties document the row references.