Connect source systems

A connection holds the address and credentials of one source system. An administrator declares each source system once, under [[connections]], and any number of contributions, in one inventory or several, use it by its id.

[[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}"

The id is unique among connections. It also names the webhook route of the connection: POST /webhooks/infrahub-prod.

GET /v1/connections lists each connection's id, type, whether it supports branches and the contributions that use it. It never returns the endpoint or the credentials.

Infrahub connections

Census reads Infrahub through its GraphQL API, at {endpoint}/graphql/{branch}.

Setting	Required	Meaning
id	Yes	The connection's id.
type	Yes	infrahub.
endpoint	Yes	The Infrahub address, for example https://infrahub.example.net.
api_key	No	Sent in the X-INFRAHUB-KEY header. Empty by default, which suits an Infrahub instance that allows anonymous reads.
branch	No	The Infrahub branch that the default view reads. Default main.
webhook_secret	No	The secret of the Infrahub webhook. When it is set, Census refuses a webhook whose signature does not match.
external_base_url	No	The address browsers use to reach Infrahub, for links to each node. Links to source objects describes it.
external_base_url_fallback	No	endpoint (default) or error.

Census builds each GraphQL query from the paths that the contributions use, so it fetches only the attributes and peers that an inventory maps. It fetches 100 nodes per request.

An Infrahub connection supports branch views: a query with branch=<name> reads that branch of Infrahub.

NetBox connections

Census reads NetBox through its REST API, at {endpoint}/api/{object type}/.

Setting	Required	Meaning
id	Yes	The connection's id.
type	Yes	netbox.
endpoint	Yes	The NetBox address, for example https://netbox.example.net.
api_key	No	The NetBox API token, sent as Authorization: Token <token>. When it is empty, Census sends no Authorization header.
external_base_url	No	The address browsers use to reach NetBox, for links to each object. Links to source objects describes it.
external_base_url_fallback	No	endpoint (default) or error.

NetBox returns whole objects, 100 per request. Census applies each contribution's paths to them.

A NetBox connection has no webhooks and no branches. Its contributions are updated by full refreshes only, and a branch view uses the NetBox default data, with the reason source does not branch.

Reuse a connection in several inventories

Two inventories can collect the same source objects through one connection, each with its own mapping. Each inventory fetches and stores its own copy, so a device can show different values in two inventories.

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

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

Links to source objects

Full-detail responses, diagnostics and the web UI give each source record a list of references to its object in the source: a link to the object's page, the NetBox API address or an Infrahub GraphQL query, and the object's id. Census builds the links from an address that a browser can reach, which is not always the endpoint Census uses, for example when Census reaches the source on an internal network.

[[connections]]
id = "netbox-prod"
type = "netbox"
endpoint = "http://netbox-internal:8000"           # the address Census uses
api_key = "${NETBOX_TOKEN}"
external_base_url = "https://netbox.example.net"   # the address in links

Settings	Address in links
external_base_url is set	external_base_url
No external_base_url, and external_base_url_fallback is endpoint or not set	endpoint
No external_base_url, and external_base_url_fallback = "error"	No link. Each record gets an error reference that says the connection has no external base URL, so the endpoint address never appears. The id reference is still given.

external_base_url must be an absolute http or https address with a host. Census refuses to start otherwise, with a message naming the connection and the setting. ${NAME} expansion applies to it.

Census builds the references each time it answers, from the stored record and the current settings. A change to either setting applies at the next start to every record, with no refresh. GET /v1/connections returns neither setting.

Trace a value to its source lists the references of each source system.

Credentials and connection errors

A connection's credentials are used only to call the source system. They never appear in an API response, in last_error or in the web UI.

When a source system cannot be reached or refuses the credentials, the refresh fails, the contribution keeps its last published data, and its health becomes degraded with the error in last_error, for example authentication failed: status 403 Forbidden.