Sync instance configuration

A configuration package defines the source, destination, and resources for a sync. Write the package as YAML or JSON and register it with infrahub-sync configs register. For a complete package, see examples/netbox_to_infrahub/package.yml. The service worker resolves the registered configuration and loads installed or pre-rendered adapter classes. Run commands select the package by the immutable configuration ID and registry version returned during registration.

The following settings can be defined:

Configuration fields

Describes the overall synchronization configuration.

Property	Type	Description	Mandatory
name	string	Unique identifier for the sync instance.	Yes
store	SyncStore	Configuration for the optional storage mechanism.	No
source	SyncAdapter	Configuration for the source adapter.	Yes
destination	SyncAdapter	Configuration for the destination adapter.	Yes
order	List of strings	Order in which objects should be synchronized. Optional — when omitted, infrahub-sync auto-computes tiers from schema_mapping.	No
schema_mapping	List of SchemaMappingModel	Defines how data is mapped from source to destination.	Yes
diffsync_flags	List of DiffSyncFlags	Instruct Infrahub Sync how to handle some specific situation without changing the data	No

Automatic write order

order: is now optional. When it is omitted, infrahub-sync derives a write-order graph from the reference: entries in each schema_mapping field and groups kinds into tiers:

• Tier 0: kinds with no outgoing references.
• Tier N: kinds whose references all live in tiers 0..N-1.

The flattened tier order replaces the manual order: list, and every planned operation records the tier its kind belongs to. A plan stores its operations ordered by (tier, operation_id) and an apply executes them in exactly that order, so a kind is written after the kinds it references.

If you must override the computed order because it does not match an adapter quirk, keep the order: list. It always wins: no tiers are computed, and each operation's recorded tier is the kind's position in the list you gave. The ordering is the same either way — the reviewed operation sequence is what an apply consumes, and there is no separate serial or parallel execution mode to choose.

Sync store

Optional configuration for a storage mechanism used for stateful synchronization.

Property	Type	Description	Mandatory
type	string	Type of the store (for example redis).	Yes
settings	Dictionary	Connection details and other settings for the store.	No

Source and Destination

Configuration for source and destination adapters.

Property	Type	Description	Mandatory
name	string	Identifier for the adapter.	Yes
settings	Dictionary	Adapter-specific settings like url and token. If not provided, values will be loaded from environment variables.	No

Schema Mapping

Defines the mappings from source to destination schemas. The tables below are the structural field reference. For the mapping syntax in depth — direct mappings, references, identifiers, filters, transforms, and worked NetBox and Nautobot examples — see Schema mapping reference.

Mapping models

Property	Type	Description	Mandatory
name	string	Infrahub model name to be mapped.	Yes
mapping	string	The source's schema mapping (API) path.	Yes
identifiers	List of strings	Fields used to uniquely identify an object.	Yes
fields	List of SchemaMappingField	Describes individual field mappings or transformations.	Yes
filters	List of SchemaMappingFilter	Filters you want to apply during the sync.	No
transforms	List of SchemaMappingTransform	Transforms you want to apply during the sync.	No

Mapping field

Property	Type	Description	Mandatory
name	string	Name of the field.	Yes
mapping	string	How the field is mapped from source to destination.	No
static	Any	A static value to assign to the field. Any declared value is assigned, including false, 0, "" and []; omit it or set it to null for no static value. Takes precedence over mapping when both are declared. See Static values for the adapters that do not assign these values yet.	No
reference	string	Reference to another object in the configuration, used if direct mapping is not applicable.	No

Mapping filters

Property	Type	Description	Mandatory
field	string	Name of the source field to filter on.	Yes
operation	string	Which filters will be applied on the field. Available operations are described below.	No
value	string	The expected value linked to the operation.	Yes except for both is_empty and is_not_empty operation

For the full list of filter operations (==, !=, >, <, >=, <=, in, not in, contains, not contains, is_empty, is_not_empty, regex, is_ip_within) with examples, see Available filter operations.

Mapping transforms

Property	Type	Description	Mandatory
field	string	Name of the target field.	Yes
expression	string	A Jinja filter compatible expression.	Yes