Create a sync project

A sync configuration is a package — a YAML or JSON file — that defines one synchronization between two systems. It has four parts: source and destination, sync order, schema mapping, and sync behavior. A Nautobot → Infrahub example runs through each. The package is registered with the Sync API; the service, not the file on disk, is what a run reads from. See Configuration package for the full envelope shape, what registration returns, and how versions and validation work.

Define the source and destination

The source and destination keys identify which adapter to use on each side of the sync and how to connect to each system. A credential-bearing setting holds a $credential reference rather than a literal value; the referenced name resolves to the name of an environment variable set on the deployment (operator.env) — see Reading from NetBox or Nautobot.

format_version: 1
configuration:
  name: example-sync-task

  source:
    name: nautobot
    settings:
      url: "https://nautobot.example.com"
      token:
        $credential: nautobot-token

  destination:
    name: infrahub
    settings:
      url: "https://infrahub.example.com"
      token:
        $credential: infrahub-token

credentials:
  nautobot-token:
    provider: env
    identifier: NAUTOBOT_TOKEN
  infrahub-token:
    provider: env
    identifier: INFRAHUB_API_TOKEN

For the full list of adapters and their connection parameters, see Choose an adapter.

Set the sync order

The order key, under configuration, specifies the sequence in which objects should be synchronized. Order matters because some objects depend on others — a device cannot be created until its location, role, and platform already exist in the destination. Omit it and the engine derives the sequence from the reference entries in schema_mapping instead.

  order:
    - "InfraDevice"
    - "InfraInterface"

Map the schema fields

The schema_mapping section, also under configuration, defines how data is translated from the source's schema into the destination's schema.

info

• The name key in the destination model corresponds to the Infrahub attribute.
• The mapping key corresponds to the key in the source payload to use.
• If reference is used, it links to a model that has been synchronized prior to this model.

  schema_mapping:
    - name: InfraDevice
      mapping: "dcim.devices"
      identifiers: ["name"]
      fields:
        - name: "name"
          mapping: "name"
        - name: "device_type"
          mapping: "device_type.display_name"
        - name: "manufacturer"
          mapping: "device_type.manufacturer.name"

    - name: InfraInterface
      mapping: "dcim.interfaces"
      identifiers: ["device", "name"]
      fields:
        - name: "name"
          mapping: "name"
        - name: "interface_type"
          static: "10gbe"
        - name: "description"
          mapping: "description"
        - name: "device"
          reference: "InfraDevice"

In this example, device_type and manufacturer are attributes of InfraDevice. For destination objects that have relationships to other models, the related models must be synchronized first — see how InfraInterface references InfraDevice via the reference key.

For the full mapping syntax — direct mappings, nested attributes, static values, references, identifiers, filters, transforms, and worked examples — see Schema mapping reference.

Tune sync behavior

The diffsync_flags key, under configuration, controls how the synchronization handles three scenarios: unmatched objects in the destination, unmatched objects in the source, and modified objects.

  # Optional: control sync behavior with diffsync flags
  diffsync_flags:
    - "SKIP_UNMATCHED_DST"  # Skip objects in destination that don't exist in source

Understanding diffsync flags

Available flags:

Flag	Description
SKIP_UNMATCHED_DST	Skip objects in the destination that don't exist in the source (prevents deletion)
SKIP_UNMATCHED_SRC	Skip objects in the source that don't exist in the destination (prevents creation)
SKIP_MODIFIED	Skip objects that exist in both systems but have different values (prevents updates)

If no flags are specified, SKIP_UNMATCHED_DST is used by default — destination objects that don't exist in the source are preserved rather than deleted.

These flags govern the live comparison that diff prints and that sync writes. They do not govern the saved plan artifact: a plan records a delete for every destination object missing from the source regardless of SKIP_UNMATCHED_DST. Recording one is not executing it — apply never executes a delete, and completes successfully while reporting how many it skipped. See Deletes in a plan.

For more on the structural field reference, see Sync instance configuration.

When the package is complete, register it — see Run a sync.