---
title: Creating a new sync instance
---

This guide will walk you through the steps to create a new sync instance for infrahub-sync, allowing you to synchronize data between your source and destination systems efficiently.

## Step 1: Define basic configuration

Start by defining your synchronization source and destination in a YAML configuration file.

```yaml
---
name: example-sync-task

source:
  name: nautobot
  settings:
    url: "https://nautobot.example.com"
    token: "NAUTOBOT_TOKEN" # This can also be loaded from environment variables

destination:
  name: infrahub
  settings:
    url: "https://infrahub.example.com"
    token: "INFRAHUB_API_TOKEN" # This can also be loaded from environment variables
```

## Step 2: Define synchronization order

The `order` key specifies the sequence in which objects should be synchronized. This is important because some objects may depend on others.

```yaml
order:
  - "InfraDevice"
  - "InfraInterface"
```

## Step 3: Configure schema mapping

The `schema_mapping` section defines how data is mapped from the source to the destination.

:::info

- The `name` key in the destination model corresponds to the Infrahub attribute.
- The `mapping` key in the destination model 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.

:::

```yaml
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. If you are using another object with a Relationship, you would need to first import those objects and then reference them (like InfraDevice in InfraInterface).

## Step 4: Configure synchronization behavior

You can control how the synchronization process handles various scenarios using DiffSync flags.

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

:::info Understanding DiffSync Flags

DiffSync flags control how the synchronization process handles various scenarios. You can add these flags to your configuration to customize the sync behavior:

```yaml
diffsync_flags:
  - "SKIP_UNMATCHED_DST"  # Default if no flags are specified
```

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, which means objects in the destination that don't exist in the source will be preserved rather than deleted.

:::

For more information on customizing your sync configuration and troubleshooting, see the [Sync Instance configuration reference](../reference/config)

The next steps will be to run the sync, you can check the [Run a sync instance guide](./run)