YAML Configuration Reference
Relevant source files
The following files were used as context for generating this wiki page:
The config.yml file defines the declarative contract for synchronizing data between a source infrastructure system and a destination infrastructure system. It specifies the connection settings for both systems, determines the mapping between source resources and destination models, and establishes the rules for filtering and transforming data during the synchronization process.
This configuration drives the infrahub-sync generate command, which renders DiffSync model classes based on these definitions and the destination schema. The core sync engine, Potenda, then uses these mappings to reconcile the state of the destination system to match the source system.
Sources: dev/knowledge/schema-mapping.md:5-10, dev/knowledge/sync-architecture.md:37-43, README.md:67-71
Core Structure
The YAML configuration consists of four primary top-level keys: name, source, destination, and schema_mapping.
| Key | Required | Description |
|---|---|---|
name | Yes | A unique identifier for the sync project. |
source | Yes | Defines the adapter and settings for the system providing data. |
destination | Yes | Defines the adapter and settings for the system receiving data. |
schema_mapping | Yes | List of mappings between source resources and destination models. |
order | No | Explicit list of models defining the synchronization sequence. |
Sources: dev/knowledge/schema-mapping.md:12-25, dev/guides/adding-an-adapter.md:79-98, AGENTS.md:65-69
Source and Destination Definitions
Both source and destination blocks require an adapter name and a settings object. The adapter field can refer to a built-in adapter name or a filesystem path to a custom Python module.
source:
name: netbox
adapter: netbox
settings:
url: "https://demo.netbox.dev"
destination:
name: infrahub
settings:
url: "http://localhost:8000"
Sources: dev/guides/adding-an-adapter.md:82-96, dev/knowledge/sync-architecture.md:19-22
Schema Mapping
The schema_mapping block is a list of SchemaMappingModel entries. Each entry defines how a specific resource in the source system corresponds to a node kind in the destination system.
The diagram shows the internal structure of a single schema mapping entry used to define data translation between systems.
Fields and Identifiers
- name: The destination model name. This must match a valid node kind in the destination schema.
- mapping: The source resource path. This is adapter-specific (e.g., a REST collection name or a dot-notation path in a JSON document).
- identifiers: A list of fields that form the DiffSync natural key. These must be stable and present on both source and destination records.
Sources: dev/knowledge/schema-mapping.md:27-33, infrahub_sync/generator/init.py:60-65
Field Mapping
Individual fields within a mapping entry are defined as SchemaMappingField objects. The engine evaluates them in a specific order of precedence:
- static: Assigns a literal value directly, ignoring source data.
- mapping: Reads a value from the source record using a dot-notation path (e.g.,
status.value). - reference: When combined with
mapping, treats the value as a foreign key to be resolved to a peer'sunique_id. - name: Specifies the destination field name.
Sources: dev/knowledge/schema-mapping.md:40-49, dev/guides/adding-an-adapter.md:60-64
Data Filtering and Transformation
Filters
Filters drop source records before they enter the sync store. A record is only kept if it satisfies all filters defined in the list.
| Operation | Description |
|---|---|
==, != | Equality and inequality checks. |
>, <, >=, <= | Numeric comparisons (coerced to integers). |
in, not in | Membership checks in a list. |
contains, not contains | String or list containment. |
is_empty, is_not_empty | Checks for null or empty values (ignores value key). |
regex | Pattern matching. |
is_ip_within | Network containment check. |
Sources: dev/knowledge/schema-mapping.md:60-75
Transforms
Transforms rewrite field values using Jinja2 expressions. They execute after filtering but before the data is loaded into the DiffSync store. The engine uses a NativeEnvironment, allowing transforms to return Python types like bool or int rather than just strings.
transforms:
- field: name
expression: "{{ name | lower }}"
- field: tags
expression: "{{ tags + ['synced'] }}"
Sources: dev/knowledge/schema-mapping.md:77-87
Synchronization Order
The order key determines the sequence in which models are written to the destination. If omitted, the system auto-computes the order by analyzing reference edges in the schema_mapping. Models that are referenced by others are prioritized and written first.
The flow shows how the synchronization sequence is determined, prioritizing dependencies to ensure relational integrity.
Sources: dev/knowledge/schema-mapping.md:51-58, dev/knowledge/sync-architecture.md:29-35
Destination Schema Definition
While config.yml maps data, the destination schema (often schema.yml for Infrahub) defines the available types and relationships. It uses generics for common attributes and nodes for specific object types.
Type Annotations
The generator maps schema attribute kinds to Python type annotations for the generated DiffSync models:
| Schema Kind | Python Type |
|---|---|
| Text, String, TextArea | str |
| Number, Integer | int |
| Boolean, Checkbox | bool |
| List | list[Any] |
Sources: infrahub_sync/generator/init.py:18-30, examples/aci_to_infrahub/schema.yml:10-50
Relationship Cardinality
Relationships in the schema determine the generated model structure:
- Cardinality "one": Annotated as
str | None. - Cardinality "many": Annotated as
list[str].
Sources: infrahub_sync/generator/init.py:127-142, examples/aci_to_infrahub/schema.yml:105-120
Summary
The YAML configuration acts as the central definition for the synchronization lifecycle. It links adapters to specific transformation logic through schema_mapping, allowing developers to define complex infrastructure data migrations without writing bespoke integration code. By leveraging identifiers, filters, and transforms, the configuration ensures that data is moved safely and accurately between disparate systems of record.
Sources: README.md:20-25, dev/knowledge/sync-architecture.md:37-43