Netbox Create Device Interfaces Task¤

task api name: create_device_interfaces

Task to create network interfaces on one or more devices in NetBox. This task creates interfaces in bulk and only if the interfaces do not already exist in NetBox, making it idempotent and safe to run multiple times.

The task supports alphanumeric range expansion, allowing you to create multiple interfaces with a single pattern. This is particularly useful for creating large numbers of similar interfaces efficiently.

Tip

The create_device_interfaces task automatically skips interfaces that already exist, preventing duplicate creation attempts and allowing for safe re-runs of automation tasks.

Interface Name Range Expansion¤

The task supports powerful range expansion patterns for creating multiple interfaces:

Numeric Ranges¤

Use [start-end] syntax to expand numeric ranges:

interface_name: "Ethernet[1-5]"
# Expands to: Ethernet1, Ethernet2, Ethernet3, Ethernet4, Ethernet5

interface_name: "Loopback[10-12]"
# Expands to: Loopback10, Loopback11, Loopback12

Comma-Separated Lists¤

Use [option1,option2,...] syntax to expand lists:

interface_name: "[ge,xe,fe]-0/0/0"
# Expands to: ge-0/0/0, xe-0/0/0, fe-0/0/0

interface_name: "Port-[A,B,C]"
# Expands to: Port-A, Port-B, Port-C

Multiple Range Patterns¤

Combine multiple range patterns in a single interface name:

interface_name: "[ge,xe]-0/0/[0-3]"
# Expands to: ge-0/0/0, ge-0/0/1, ge-0/0/2, ge-0/0/3,
#             xe-0/0/0, xe-0/0/1, xe-0/0/2, xe-0/0/3

Multiple Interface Names¤

Pass a list of interface names (with or without ranges):

interface_name: 
  - "Loopback[1-3]"
  - "Management1"
  - "[ge,xe]-0/1/0"
# Expands to: Loopback1, Loopback2, Loopback3, Management1, ge-0/1/0, xe-0/1/0

Branching Support¤

Create Device Interfaces task is branch aware and can create interfaces within a branch. Netbox Branching Plugin needs to be installed on the Netbox instance.

When using branches, interfaces are created in the specified branch and can be reviewed before merging into the main database.

NORFAB Netbox Create Device Interfaces Command Shell Reference¤

NorFab shell supports these command options for Netbox create_device_interfaces task:

nf#man tree netbox.create.device-interfaces
root
└── netbox:    Netbox service
    └── create:    Create objects in Netbox
        └── device-interfaces:    Create devices interfaces
            ├── instance:    Netbox instance name to target
            ├── dry-run:    Do not commit to database
            ├── branch:    Branching plugin branch name to use
            ├── *devices:    List of device names or device objects to create interfaces for
            ├── *interface_name:    Name(s) of the interface(s) to create
            ├── interface-type:    Name(s) of the interface(s) to create, default 'other'
            ├── description:    Interface description
            ├── speed:    Interface speed in Kbps
            ├── mtu:    Maximum transmission unit size in bytes
            ├── timeout:    Job timeout
            ├── workers:    Filter worker to target, default 'any'
            ├── verbose-result:    Control output details, default 'False'
            └── progress:    Display progress events, default 'True'
nf#

Usage Examples¤

Basic Interface Creation¤

Create a single interface on one device:

from norfab.core.nfapi import NorFab

nf = NorFab()
result = nf.run_job(
    service="netbox",
    task="create_device_interfaces",
    workers="any",
    kwargs={
        "devices": ["switch-01", "switch-02"],
        "interface_name": "Loopbback[0-5]",
        "interface_type": "virtual",
        "description": "Test interfaces"
    }
)

Interface Types¤

Common interface types supported by NetBox:

virtual - Virtual interfaces (loopbacks, tunnel interfaces)
lag - Link Aggregation Group (Port-Channel, bond)
1000base-t - 1G copper Ethernet
10gbase-x-sfpp - 10G SFP+ Ethernet
25gbase-x-sfp28 - 25G SFP28 Ethernet
40gbase-x-qsfpp - 40G QSFP+ Ethernet
100gbase-x-qsfp28 - 100G QSFP28 Ethernet
other - Generic interface type (default)

Refer to your NetBox instance for the complete list of available interface types.

Error Handling¤

Task handles several error conditions gracefully:

Non-existent Device: If a device doesn't exist in NetBox, an error is logged but processing continues for other devices
Duplicate Interfaces: Existing interfaces are automatically skipped and listed in the skipped array
Invalid Interface Type: NetBox will reject invalid interface types with an error message
Branch Not Found: If a specified branch doesn't exist and the branching plugin is not available, the task will fail

Best Practices¤

Use Dry Run First: Always test with dry_run: True before creating interfaces in production
Meaningful Names: Use descriptive interface names that match your device's actual interface naming
Consistent Types: Use appropriate interface types that match the physical/virtual nature of the interfaces
Batch Operations: Create multiple interfaces in a single call for efficiency
Branch Usage: Use branches for testing bulk operations before committing to the main database
Idempotency: The task is idempotent - running it multiple times with the same parameters is safe

Python API Reference¤

Create interfaces for one or more devices in NetBox. This task creates interfaces in bulk and only if interfaces does not exist in Netbox.

Parameters:

Name	Type	Description	Default
`job`	`Job`	The job object containing execution context and metadata.	required
`devices`	`list`	List of device names or device objects to create interfaces for.	required
`interface_name`	`Union[list, str]`	Name(s) of the interface(s) to create. Can be a single interface name as a string or multiple names as a list. Alphanumeric ranges are supported for bulk creation: Ethernet[1-3] -> Ethernet1, Ethernet2, Ethernet3 [ge,xe]-0/0/[0-9] -> ge-0/0/0, ..., xe-0/0/0 etc.	`None`
`interface_type`	`str`	Type of interface (e.g., "other", "virtual", "lag", "1000base-t"). Defaults to "other".	`'other'`
`instance`	`Union[None, str]`	NetBox instance identifier to use. If None, uses the default instance. Defaults to None.	`None`
`dry_run`	`bool`	If True, simulates the operation without making actual changes. Defaults to False.	`False`
`branch`	`str`	NetBox branch to use for the operation. Defaults to None.	`None`
`kwargs`	`dict`	Any additional interface attributes	`{}`
`interfaces_data`	`list`	List of per-interface payload dictionaries. Each dictionary supports all NetBox interface create fields and must include `name`. This is used for true bulk create with heterogeneous interface attributes.	`None`

Returns:

Name	Type	Description
`Result`	`Result`	Result object containing the task name, execution results, and affected resources. The result dictionary contains status and details of interface creation operations.

Source code in norfab\workers\netbox_worker\interfaces_tasks.py

@Task(
    fastapi={"methods": ["GET"], "schema": NetboxFastApiArgs.model_json_schema()},
    input=CreateDeviceInterfacesInput,
)
def create_device_interfaces(
    self,
    job: Job,
    devices: list,
    interface_name: Union[None, list, str] = None,
    interfaces_data: Union[None, list] = None,
    interface_type: str = "other",
    instance: Union[None, str] = None,
    dry_run: bool = False,
    branch: str = None,
    **kwargs: dict,
) -> Result:
    """
    Create interfaces for one or more devices in NetBox. This task creates interfaces in bulk and only
    if interfaces does not exist in Netbox.

    Args:
        job (Job): The job object containing execution context and metadata.
        devices (list): List of device names or device objects to create interfaces for.
        interface_name (Union[list, str]): Name(s) of the interface(s) to create. Can be a single
            interface name as a string or multiple names as a list. Alphanumeric ranges are
            supported for bulk creation:

            - Ethernet[1-3] -> Ethernet1, Ethernet2, Ethernet3
            - [ge,xe]-0/0/[0-9] -> ge-0/0/0, ..., xe-0/0/0 etc.

        interface_type (str, optional): Type of interface (e.g., "other", "virtual", "lag",
            "1000base-t"). Defaults to "other".
        instance (Union[None, str], optional): NetBox instance identifier to use. If None,
            uses the default instance. Defaults to None.
        dry_run (bool, optional): If True, simulates the operation without making actual changes.
            Defaults to False.
        branch (str, optional): NetBox branch to use for the operation. Defaults to None.
        kwargs (dict, optional): Any additional interface attributes
        interfaces_data (list, optional): List of per-interface payload dictionaries.
            Each dictionary supports all NetBox interface create fields and must
            include ``name``. This is used for true bulk create with heterogeneous
            interface attributes.

    Returns:
        Result: Result object containing the task name, execution results, and affected resources.
            The result dictionary contains status and details of interface creation operations.
    """
    instance = instance or self.default_instance
    result = {}
    kwargs = kwargs or {}
    ret = Result(
        task=f"{self.name}:create_device_interfaces",
        result=result,
        resources=[instance],
    )
    nb = self._get_pynetbox(instance, branch=branch)
    log.info(
        f"{self.name} - Create device interfaces: Creating interfaces for {len(devices)} device(s) in '{instance}'"
    )

    payloads_by_name = {}
    if interfaces_data:
        for item in interfaces_data:
            payloads_by_name[str(item["name"])] = dict(item)
        all_interface_names = sorted(payloads_by_name.keys())
        job.event(
            f"received {len(all_interface_names)} interface create payload(s)"
        )
    else:
        # Normalize interface_name to a list and expand patterns
        interface_names = (
            [interface_name]
            if isinstance(interface_name, str)
            else (interface_name or [])
        )
        all_interface_names = []
        for name_pattern in interface_names:
            all_interface_names.extend(expand_alphanumeric_range(name_pattern))
        job.event(
            f"expanded interface names to {len(all_interface_names)} interface(s)"
        )

    # Process each device
    for device_name in devices:
        result[device_name] = {
            "created": [],
            "skipped": [],
        }

        nb_device = nb.dcim.devices.get(name=device_name)
        if not nb_device:
            msg = f"device '{device_name}' not found in NetBox"
            ret.errors.append(msg)
            job.event(msg, severity="WARNING")
            log.warning(f"{self.name} - {msg}")
            continue

        existing_interface_names = {
            intf.name for intf in nb.dcim.interfaces.filter(device=device_name)
        }
        interfaces_to_create = []

        for intf_name in all_interface_names:
            if intf_name in existing_interface_names:
                result[device_name]["skipped"].append(intf_name)
                job.event(
                    f"skipping '{intf_name}' on '{device_name}' - already exists"
                )
                continue
            if payloads_by_name:
                intf_data = {"device": nb_device.id, **payloads_by_name[intf_name]}
                intf_data.setdefault("type", interface_type)
            else:
                intf_data = {
                    "device": nb_device.id,
                    "name": intf_name,
                    "type": interface_type,
                    **kwargs,
                }
            interfaces_to_create.append(intf_data)
            result[device_name]["created"].append(intf_name)

        if interfaces_to_create:
            if dry_run is True:
                job.event(
                    f"dry-run, would create {len(interfaces_to_create)} interface(s) on '{device_name}'"
                )
            else:
                try:
                    nb.dcim.interfaces.create(interfaces_to_create)
                    msg = f"created {len(interfaces_to_create)} interface(s) on '{device_name}'"
                    job.event(msg)
                    log.info(f"{self.name} - {msg}")
                except Exception as e:
                    msg = f"failed to create interfaces on '{device_name}': {e}"
                    ret.errors.append(msg)
                    log.error(f"{self.name} - {msg}")
                    job.event(msg, severity="ERROR")

    return ret