How to use the NetBox plugin

Manage devices, IP addresses, sites, device roles, platforms, and contact assignments in NetBox from Kestra flows.

Authentication

All tasks require url (the NetBox API base URL, required) and token (a NetBox API token, required). Optionally set options for HTTP client configuration. Store secrets in secrets and set connection properties on each task.

Tasks

device.Create creates a device — set url, token, name, deviceType, deviceRole, and site (all required). Optionally set rack, position, face, status, description, tags, and customFields. Outputs id, name, and url.

device.List lists devices: set url and token (required). Optionally set filters (map of filter parameters), limit (default 100), fields (subset of fields to return), and fetchType (FETCH, FETCH_ONE, STORE or NONE, default FETCH). Outputs size, total, and rows/row/uri depending on fetchType. platform and custom_fields are returned by default as nested objects, and only need to be listed when fields is set.

device.Update updates a device — set url, token, and deviceId (all required). Optionally set partialUpdate (use PATCH instead of PUT, default true) and any device fields to change (name, deviceType, deviceRole, site, rack, position, face, status, description, comments, tags, customFields). Outputs id, name, and url.

contactassignment.Create assigns a contact to an object — set url, token, contentType, objectId, contactId, and roleId (all required). Optionally set priority. Outputs id, url, display, contentType, and objectId.

contactassignment.List lists contact assignments — same options as device.List. Outputs size, total, and rows/row/uri.

site.List lists sites — same options as device.List. Outputs size, total, and rows/row/uri.

devicerole.List lists device roles (/api/dcim/device-roles/), with the same options as device.List. Outputs size, total, and rows/row/uri.

platform.List lists platforms (/api/dcim/platforms/), with the same options as device.List. Outputs size, total, and rows/row/uri.

ipam.AssignIpAddress creates and optionally assigns an IP address — set url and token (required). Optionally set address, prefixId (allocate next available from prefix), status, assignedObjectType, assignedObjectId, dnsName, addressDescription, role, tags, and customFields. Outputs id, address, and url.

List task behavior

All *.List tasks share the same options and behavior:

• limit is the page size of each NetBox request (minimum 1, default 100). It does not cap the result: all pages are fetched until NetBox reports no next page. FETCH_ONE and NONE make a single one-row request instead.
• FETCH keeps every row in the execution outputs. Use fetchType: STORE for large or unfiltered lists, such as a full device inventory.
• filters entries are sent to NetBox unchanged, so custom field filters work with the cf_ prefix (for example cf_poc_pair: 1).
• A list value becomes a repeated query key: name: [edge-01a, edge-01b] is sent as name=edge-01a&name=edge-01b.

Example: dynamic dropdowns from NetBox

A scheduled flow stores the sites, roles and devices in the namespace KV store, with devices grouped by <site>/<role>. A form flow reads them with kv() in the expression of its inputs, and the devices input uses dependsOn to list only the devices of the selected site and role.

id: sync_netbox_dropdown_values
namespace: company.team

tasks: 
  - id: list_sites
    type: io.kestra.plugin.ee.netbox.site.List
    url: "{{ secret('NETBOX_URL') }}"
    token: "{{ secret('NETBOX_API_TOKEN') }}"
    fields: 
      - "slug"

  - id: list_roles
    type: io.kestra.plugin.ee.netbox.devicerole.List
    url: "{{ secret('NETBOX_URL') }}"
    token: "{{ secret('NETBOX_API_TOKEN') }}"
    fields: 
      - "slug"

  - id: list_devices
    type: io.kestra.plugin.ee.netbox.device.List
    url: "{{ secret('NETBOX_URL') }}"
    token: "{{ secret('NETBOX_API_TOKEN') }}"
    filters: 
      status: "active"
    fields: 
      - "name"
      - "site"
      - "role"

  - id: store_sites
    type: io.kestra.plugin.core.kv.Set
    key: netbox_sites
    value: "{{ outputs.list_sites.rows | jq('map(.slug)') | first }}"

  - id: store_roles
    type: io.kestra.plugin.core.kv.Set
    key: netbox_device_roles
    value: "{{ outputs.list_roles.rows | jq('map(.slug)') | first }}"

  - id: store_devices
    type: io.kestra.plugin.core.kv.Set
    key: netbox_devices
    value: "{{ outputs.list_devices.rows | jq('map(select(.name != null) | {key: (.site.slug + \"/\" + .role.slug), value: .name}) | group_by(.key) | map({key: .[0].key, value: map(.value)}) | from_entries') | first }}"

triggers: 
  - id: hourly
    type: io.kestra.plugin.core.trigger.Schedule
    cron: "0 * * * *"

FETCH keeps every listed row in the execution outputs, so filter large inventories. Run the sync flow once before opening the form, because kv() fails while a key does not exist yet.

id: provision_device_form
namespace: company.team

inputs: 
  - id: site
    type: SELECT
    expression: "{{ kv('netbox_sites') }}"

  - id: role
    type: SELECT
    expression: "{{ kv('netbox_device_roles') }}"

  - id: devices
    type: MULTISELECT
    dependsOn: 
      inputs: 
        - site
        - role
    expression: "{{ kv('netbox_devices')[inputs.site ~ '/' ~ inputs.role] | default([]) }}"

tasks: 
  - id: log_selection
    type: io.kestra.plugin.core.log.Log
    message: "Upgrading {{ inputs.devices | join(', ') }} in {{ inputs.site }} ({{ inputs.role }})"