Skip to main content

Administration

An administrator deploys Census and defines the inventories it exposes. Everything an administrator sets is in one TOML configuration file. Census reads it at startup, checks every rule before it connects to anything, and applies the changes since the previous start. There is no API to change the configuration.

Steps to expose an inventory​

  1. Deploy Census and Memgraph, and set the server address and the Memgraph connection.
  2. Declare a connection for each source system: Infrahub or NetBox, its address and its credentials.
  3. Define an inventory: its id, description, entity kind and fields.
  4. Add a contribution for each source that supplies the inventory: the object types to collect, the source field that supplies the HFID, and the source field of each inventory field.
  5. Set the priorities that decide which source supplies each field when sources disagree.
  6. Optionally, declare vocabularies so that each source's spellings map to one list of canonical values.
  7. Declare the location hierarchy and map each source's location fields to it.
  8. Set the freshness budgets that tell consumers when a value is stale.
  9. For Infrahub, send webhooks to Census so that changes arrive between full refreshes.
  10. Restart Census, then check the inventory's completeness and diagnostics in the web UI or through the diagnostics API.

After the first start, each configuration change is applied at the next restart. Some changes delete a contribution's records until its next refresh, and some make the inventory answer 503 inventory-rebuilding until Census has recomputed it.

The configuration reference lists every setting and every rule Census checks at startup.

A complete example​

This file defines one inventory, devices, filled from one Infrahub connection and one NetBox connection. The other pages of this section explain each part. The repository's config.toml.example contains the same example.

[server]
bind = "0.0.0.0:8080"

[memgraph]
bolt_url = "${MEMGRAPH_BOLT_URL:-bolt://localhost:7687}"

[branching]
max_views = 3
idle_ttl = "1h"

[[connections]]
id = "infrahub-prod"
type = "infrahub"
endpoint = "https://infrahub.example.net"
api_key = "${INFRAHUB_API_KEY}"
branch = "main"
webhook_secret = "${INFRAHUB_WEBHOOK_SECRET}"

[[connections]]
id = "netbox-prod"
type = "netbox"
endpoint = "https://netbox.example.net"
api_key = "${NETBOX_TOKEN}"

[inventories.devices]
description = "Network devices from Infrahub and NetBox"
entity_kind = "device"
priority = ["infrahub", "netbox"]

[inventories.devices.freshness]
default = "1h"
status = "30s"

[inventories.devices.fields.role]
type = "string"

[inventories.devices.fields.status]
type = "string"
vocabulary = ["active", "planned", "offline"]
default = "offline"
priority = ["netbox", "infrahub"]

[inventories.devices.fields.serial]
type = "string"

[inventories.devices.fields.ports]
type = "number"

[inventories.devices.location]
levels = ["region", "site", "rack"]
locations = [
  "eu", "eu/par1", "eu/par1/r01", "eu/par1/r02",
  "us", "us/nyc1", "us/nyc1/r01",
]

[[inventories.devices.contributions]]
id = "infrahub"
connection = "infrahub-prod"
object_types = ["InfraDevice"]
hfid = "name.value"
refresh_interval = "5m"

[inventories.devices.contributions.attributes]
role = "role.value"
status = "status.value"

[inventories.devices.contributions.values.status]
"in-service" = "active"
"provisioning" = "planned"

[inventories.devices.contributions.location]
site = "site.node.name.value"

[inventories.devices.contributions.location_values.site]
"PAR-1" = "par1"

[[inventories.devices.contributions]]
id = "netbox"
connection = "netbox-prod"
object_types = ["dcim/devices"]
hfid = "name"

[inventories.devices.contributions.attributes]
role = "role.name"
status = "status.value"
serial = "serial"

[inventories.devices.contributions.defaults]
status = "planned"

[inventories.devices.contributions.location]
site = "site.slug"
rack = "rack.name"