# netbox_device – Create, update or delete devices within Netbox

New in version 2.8.

- Synopsis
- Requirements
- Parameters
- Notes
- Examples
- Return Values
- Status

## Synopsis

- Creates, updates or removes devices from Netbox

## Requirements

The below requirements are needed on the host that executes this module.

- pynetbox

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
data - / required |  | Defines the device configuration
| asset_tag - |  | Asset tag that is associated to the device
| cluster - |  | Cluster that the device will be assigned to
| comments - |  | Comments that may include additional information in regards to the device
| custom_fields - |  | must exist in Netbox
| device_role - |  | Required if state=present and the device does not exist yet
| device_type - |  | Required if state=present and the device does not exist yet
| face - |  | Required if rack is defined
| name - / required |  | The name of the device
| platform - |  | The platform of the device
| position - |  | The position of the device in the rack defined above
| rack - |  | The name of the rack to assign the device to
| serial - |  | Serial number of the device
| site - |  | Required if state=present and the device does not exist yet

status
-

Choices:
- Active
- Offline
- Planned
- Staged
- Failed
- Inventory

The status of the device

| tags - |  | Any tags that the device may need to be associated with
| tenant - |  | The tenant that the device will be assigned to
netbox_token - / required |  | The token created within Netbox to authorize API access
netbox_url - / required |  | URL of the Netbox instance resolvable by Ansible control host

state
-

Choices:
- absent
- present ←

Use `present` or `absent` for adding or removing.

validate_certs
boolean

Choices:
- no
- yes ←

If `no`, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates.

## Notes

Note

- Tags should be defined as a YAML list
- This should be ran with connection `local` and hosts `localhost`

## Examples

    - name: "Test Netbox modules"
      connection: local
      hosts: localhost
      gather_facts: False

      tasks:
        - name: Create device within Netbox with only required information
          netbox_device:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              name: Test Device
              device_type: C9410R
              device_role: Core Switch
              site: Main
            state: present

        - name: Delete device within netbox
          netbox_device:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              name: Test Device
            state: absent

        - name: Create device with tags
          netbox_device:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              name: Another Test Device
              device_type: C9410R
              device_role: Core Switch
              site: Main
              tags:
                - Schnozzberry
            state: present

        - name: Update the rack and position of an existing device
          netbox_device:
            netbox_url: http://netbox.local
            netbox_token: thisIsMyToken
            data:
              name: Test Device
              rack: Test Rack
              position: 10
              face: Front
            state: present

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Returned | Description
--- | --- | ---
device dictionary | success (when state=present) | Serialized object as created or already existent within Netbox
msg string | always | Message indicating failure or info about what has been achieved

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Mikhail Yohman (@FragmentedPacket)
- David Gomez (@amb1s1)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.