Netbox Create IP Bulk Task

task api name: create_ip_bulk

Allocates IP addresses for multiple device interfaces. The task first retrieves matching interfaces with get_interfaces, then calls create_ip for each device/interface pair.

Inputs

Parameter	Required	Description
prefix	Yes	Parent prefix as a network string, prefix description, or pynetbox filter dictionary
devices	Yes	Device names to assign IP addresses to
interface_list	No	Exact interface names to target
interface_regex	No	Regex pattern to match interface names
description	No	Description for allocated IP addresses
vrf	No	VRF name for allocated IP addresses
tags	No	Tags to associate with allocated IP addresses
dns_name	No	DNS name for allocated IP addresses
tenant	No	Tenant name to associate with allocated IP addresses
comments	No	IP address comments
role	No	IP address role
status	No	IP address status
is_primary	No	Set each IP as the primary IP for its device
mask_len	No	Allocate child subnets of this length before creating IPs
create_peer_ip	No	Create IP addresses for connected peer interfaces, default True
instance	No	NetBox instance name to target
branch	No	NetBox Branching plugin branch name to write to
dry_run	No	Preview allocations without writing

Output

Returns allocation results keyed by device and interface:

{
    "ceos-leaf-1": {
        "Ethernet1": {
            "address": "10.0.0.1/31",
            "...": "...",
        },
    },
}

Notes / Gotchas

• interface_list takes precedence over interface_regex when both are provided.
• Dry-run mode passes through to create_ip; the same mask_len dry-run limitation applies.
• mask_len=32 or mask_len=128 is invalid with create_peer_ip=True.
• Branch writes require the NetBox Branching Plugin.

Examples

CLIPython

Allocate IPs for selected interfaces:

nf#netbox create ip-bulk prefix 10.0.0.0/24 devices ceos-leaf-1 ceos-leaf-2 interface-list Ethernet1 Ethernet2

Allocate IPs for interfaces matching a regex:

nf#netbox create ip-bulk prefix 10.0.0.0/24 devices ceos-leaf-1 interface-regex "Ethernet[1-4]" mask-len 31

Preview allocations:

nf#netbox create ip-bulk prefix 10.0.0.0/24 devices ceos-leaf-1 interface-list Ethernet1 dry-run

from norfab.core.nfapi import NorFab

nf = NorFab(inventory="./inventory.yaml")
nf.start()
client = nf.make_client()

# allocate IPs for selected interfaces
result = client.run_job(
    "netbox",
    "create_ip_bulk",
    workers="any",
    kwargs={
        "prefix": "10.0.0.0/24",
        "devices": ["ceos-leaf-1", "ceos-leaf-2"],
        "interface_list": ["Ethernet1", "Ethernet2"],
    },
)

# allocate /31 link subnets for matching interfaces
result = client.run_job(
    "netbox",
    "create_ip_bulk",
    workers="any",
    kwargs={
        "prefix": {"prefix": "10.0.0.0/24", "site": "lab"},
        "devices": ["ceos-leaf-1"],
        "interface_regex": "Ethernet[1-4]",
        "mask_len": 31,
        "description": "fabric uplink",
    },
)

nf.destroy()

NORFAB Netbox Create IP Bulk Command Shell Reference

NorFab shell supports these command options for Netbox create_ip_bulk task:

nf# man tree netbox.create.ip-bulk
root
└── netbox:    Netbox service
    └── create:    Create objects in Netbox
        └── ip-bulk:    Allocate next available IP address from prefix for multiple devices and interfaces
            ├── timeout:    Job timeout
            ├── workers:    Filter worker to target, default 'any'
            ├── verbose-result:    Control output details, default 'False'
            ├── progress:    Display progress events, default 'True'
            ├── nowait:    Do not wait for job to complete, default 'False'
            ├── instance:    Netbox instance name to target
            ├── dry-run:    Do not commit to database
            ├── branch:    Branching plugin branch name to use
            ├── prefix:    Prefix to allocate IP address from, can also provide prefix name or filters
            ├── devices:    List of device names to create IP address for
            ├── interface-regex:    Regular expression of device interface names to create IP address for
            ├── interface-list:    List of interface names to create IP address for
            ├── description:    IP address description
            ├── vrf:    VRF to associate with IP address
            ├── tags:    Tags to add to IP address
            ├── dns-name:    IP address DNS name
            ├── tenant:    Tenant name to associate with IP address
            ├── comments:    IP address comments field
            ├── role:    IP address functional role
            ├── mask-len:    Mask length to use for IP address
            ├── create-peer-ip:    Create link peer IP address as well
            └── status:    IP address status
nf#

Python API Reference

Bulk assigns IP addresses to interfaces of specified devices.

.. warning::

**Dry-run limitation**: when ``dry_run=True``, ``mask_len`` is ignored and
the same candidate IP address (taken directly from the parent prefix using
the parent prefix mask length) is returned for every interface — no child
subnets are created.

Parameters:

Name	Type	Description	Default
job	Job	The job instance used for logging and tracking the task.	required
prefix	Union[str, dict]	The prefix to allocate IPs from; IPv4/IPv6 network string, prefix description, or dict with pynetbox filter keys.	required
devices	list[str]	List of device names to assign IP addresses to.	None
interface_list	list[str]	List of specific interface names to target. Takes precedence over interface_regex when both are provided.	None
interface_regex	str	Regex pattern to match interface names.	None
instance	str	The NetBox instance name to use.	None
dry_run	bool	If True, preview changes without committing to NetBox.	False
branch	str	NetBox branching plugin branch name to use.	None
description	str	Description for the allocated IP addresses.	None
vrf	str	VRF name for the IP addresses.	None
tags	list	List of tags to associate with the IP addresses.	None
dns_name	str	DNS name for the IP addresses.	None
tenant	str	Tenant name to associate with the IP addresses.	None
comments	str	Additional comments for the IP addresses.	None
role	str	Role for the IP addresses, e.g. 'loopback', 'anycast'.	None
status	str	Status for the IP addresses, e.g. 'active', 'reserved', 'deprecated'.	None
is_primary	bool	If True, set each IP as the primary IP for its device.	None
mask_len	int	Mask length for the IP addresses; creates a child subnet of this length within the parent prefix. Ignored when dry_run=True.	None
create_peer_ip	bool	If True, creates an IP address for the link peer interface.	True

Returns:

Name	Type	Description
Result	Result	A Result object containing per-device, per-interface IP allocation results.

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

@Task(
    fastapi={"methods": ["POST"], "schema": NetboxFastApiArgs.model_json_schema()},
    input=CreateIpBulkInput,
    output=CreateIpBulkResult,
    mcp={
        "annotations": {
            "title": "Create IP Addresses Bulk",
            "readOnlyHint": False,
            "destructiveHint": False,
            "idempotentHint": False,
            "openWorldHint": True,
        }
    },
)
def create_ip_bulk(
    self,
    job: Job,
    prefix: Union[str, dict],
    devices: list[str] = None,
    interface_list: list[str] = None,
    interface_regex: str = None,
    instance: Union[None, str] = None,
    dry_run: Union[None, bool] = False,
    branch: Union[None, str] = None,
    description: Union[None, str] = None,
    vrf: Union[None, str] = None,
    tags: Union[None, list] = None,
    dns_name: Union[None, str] = None,
    tenant: Union[None, str] = None,
    comments: Union[None, str] = None,
    role: Union[None, str] = None,
    status: Union[None, str] = None,
    is_primary: Union[None, bool] = None,
    mask_len: Union[None, int] = None,
    create_peer_ip: Union[None, bool] = True,
) -> Result:
    """
    Bulk assigns IP addresses to interfaces of specified devices.

    .. warning::

        **Dry-run limitation**: when ``dry_run=True``, ``mask_len`` is ignored and
        the same candidate IP address (taken directly from the parent prefix using
        the parent prefix mask length) is returned for every interface — no child
        subnets are created.

    Args:
        job (Job): The job instance used for logging and tracking the task.
        prefix (Union[str, dict]): The prefix to allocate IPs from; IPv4/IPv6 network
            string, prefix description, or dict with pynetbox filter keys.
        devices (list[str], optional): List of device names to assign IP addresses to.
        interface_list (list[str], optional): List of specific interface names to target.
            Takes precedence over `interface_regex` when both are provided.
        interface_regex (str, optional): Regex pattern to match interface names.
        instance (str, optional): The NetBox instance name to use.
        dry_run (bool, optional): If True, preview changes without committing to NetBox.
        branch (str, optional): NetBox branching plugin branch name to use.
        description (str, optional): Description for the allocated IP addresses.
        vrf (str, optional): VRF name for the IP addresses.
        tags (list, optional): List of tags to associate with the IP addresses.
        dns_name (str, optional): DNS name for the IP addresses.
        tenant (str, optional): Tenant name to associate with the IP addresses.
        comments (str, optional): Additional comments for the IP addresses.
        role (str, optional): Role for the IP addresses, e.g. 'loopback', 'anycast'.
        status (str, optional): Status for the IP addresses, e.g. 'active', 'reserved', 'deprecated'.
        is_primary (bool, optional): If True, set each IP as the primary IP for its device.
        mask_len (int, optional): Mask length for the IP addresses; creates a child subnet
            of this length within the parent prefix. Ignored when ``dry_run=True``.
        create_peer_ip (bool, optional): If True, creates an IP address for the link peer interface.

    Returns:
        Result: A Result object containing per-device, per-interface IP allocation results.
    """
    instance = instance or self.default_instance
    log.info(
        f"{self.name} - Create IP bulk: Assigning IPs for {len(devices or [])} device(s) from '{instance}' Netbox"
    )
    ret = Result(
        task=f"{self.name}:create_ip_bulk", result={}, resources=[instance]
    )
    job.event(
        f"creating IP addresses in bulk for {len(devices)} device(s), dry_run={dry_run}"
    )

    # get list of all interfaces
    interfaces = self.get_interfaces(
        job=job,
        devices=devices,
        interface_list=interface_list,
        interface_regex=interface_regex,
        instance=instance,
        branch=branch,
    )
    if interfaces.errors:
        job.event(
            "failed to retrieve interfaces for bulk IP creation", severity="ERROR"
        )
        ret.errors.extend(interfaces.errors)
        ret.failed = True
        return ret
    interface_count = sum(len(v) for v in interfaces.result.values())
    job.event(f"retrieved {interface_count} interface(s) for bulk IP creation")

    # iterate over interfaces and assign IP addresses
    job.event(f"processing {interface_count} interface(s) for bulk IP creation")
    for device, device_interfaces in interfaces.result.items():
        ret.result[device] = {}
        for interface in sorted(device_interfaces.keys()):
            create_ip = self.create_ip(
                job=job,
                device=device,
                interface=interface,
                instance=instance,
                prefix=prefix,
                dry_run=dry_run,
                branch=branch,
                description=description,
                vrf=vrf,
                tags=tags,
                dns_name=dns_name,
                tenant=tenant,
                comments=comments,
                role=role,
                status=status,
                is_primary=is_primary,
                mask_len=mask_len,
                create_peer_ip=create_peer_ip,
            )
            ret.result[device][interface] = create_ip.result

    if dry_run is True:
        ret.dry_run = True

    job.event("bulk IP address creation task complete")
    return ret