example.yml

# The scripts in this repo with a --yaml argument assume that the YAML file pointed to contains the YAML structure below.
# 
---
# Color choices are used in both device_roles and tags.
# Netbox requires RGB values, but the scripts in this
# repo accept the below color choices and convert them to
# RGB when submitting requests to Netbox.  We'll add more 
# colors later if needed.
# blue
# cyan
# green
# green_dark
# indigo
# orange
# purple
# red
# teal
# yellow
# gray_light
# gray
# gray_dark

# Tags
# Mandatory keys
#   - name: name of the tag
#   - color: color from the color choices at the top of this file
#
# Optional keys
#   - description: describes what the tag signifies
# Below are some suggested tags.
# Use the script ./device_print_filtered.py with the --tags argument to filter
# on tags.  Example:
# ./device_print_filtered.py --tags cleanup,lab_tor
# The above would filter one all lab_tor devices that need to be cleaned up (if any)
tags:
  # TODO/Action tags
  cleanup:
    name: cleanup
    color: yellow
    description: Items to be cleaned up
  # Usage tags
  lab_tor:
    name: lab_tor
    color: teal
    description: lab L2 switches for mgmt vlans
  lab_gateway:
    name: lab_gateway
    color: green_dark
    description: lab gateways (typically host 1 on each vlan)
  lab_ts:
    name: lab_ts
    color: orange
    description: lab terminal servers
  tgen:
    name: tgen
    color: purple
    description: traffic generators
  # People (I use color blue for people and use their email alias for name)
  c3po:
    name: c3po
    color: blue
  yoda:
    name: yoda
    color: blue
  # projects (I use color red)
  starbase_nw:
    name: starbase
    color: red
    description: Build starbase in the northwest quadrant
  # Lab Admin (I use color gray)
  infra:
    name: infra
    color: gray
    description: any lab infra devices e.g. terminal servers, gateways, etc

# Sites
# Mandatory keys:
#   name: name of the site
#   status: status of the site (Active, Planned, Staging, Decommissioning, Retired)
#
# Optional keys:
#   description: free-form description
#   tags: YAML list of tags to allow later searching by tag
sites:
  mysite:
    name: mysite
    status: Active
    description: This describes mysite

# Prefixes
# Mandatory keys:
#   prefix: e.g. 192.168.1.0/24
# Optional keys:
#   site: The site in which the prefix resides (must match a site in the sites: section of this file)
#   description: free-form description for the prefix
#   status: Operational status of this prefix. Valid values: container, active, reserved, deprecated
#   vlan: vlan ID aka vid
prefixes:
  192.168.5.0/24:
    prefix: 192.168.5.0/24
    site: mysite
    vlan: 5
    status: active
    description: Vlan5, row-a

# Racks
# Mandatory keys:
#   name: Name of the rack
#   location: Location in which rack is installed e.g. row-v
#   site: Site in which rack is installed. Must be present in the 
#         sites section of this file.
# Optional keys:
#   comments: Free-form comment for this rack
#   tags: yaml list of tags for this rack. Tags must already exist in Netbox.
#   u_height: How many RU are in this rack (typically 42 or 48)
racks:
  rack_1:
    name: rack_1
    comments: This is a comment for rack_1
    location: row-a
    site: mysite
    tags:
      - infra
      - admin
    u_height: 48

# Locations
# Mandatory keys
#   name: Name of the location
#   site: Site which contains the location
locations:
  row-a:
    name: row-a
    site: mysite

# Manufacturers
# Mandatory keys
#   name: Name of the manufacturer
#
# NOTES:
# 1. Manufacturer name is compared to existing manufacturers in Netbox.  
#    If the name differs even slightly, it will result in a new manufacturer
#    being created.  E.g. 'Cisco Systems, Inc.' is a different manufacturer
#    than 'Cisco Systems, Inc'  For this reason, it might be good to keep 
#    these names simple, e.g. cisco, arista, juniper, etc.
manufacturers:
  cisco:
    name: cisco
  arista:
    name: arista
  juniper:
    name: juniper
  spirent:
    name: spirent

# Device Types
# Mandatory keys
#   model: The device's model number
#   manufacturer: The device's manufacturer.
#
# Optional keys
#   u_height: Height of the device, in RU.  e.g. N9K-C9504 is 7 RU
#   comments: Free form comment for the device
# NOTES:
# 1. The manufacturer string must match one of the entries
#    in manufacturers section in this file.
device_types:
  CISCO-UNKNOWN:
    model: CISCO-UNKNOWN
    manufacturer: cisco
  CISCO-2600:
    model: CISCO-2600
    manufacturer: cisco
    u_height: 1
  N3K-C3048TP-1GE:
    model: N3K-C3048TP-1GE
    manufacturer: cisco
    u_height: 1
  N3K-C3172TQ-XL:
    model: N3K-C3172TQ-XL
    manufacturer: cisco
    u_height: 1
    comments: 48x10GT + 6x40G Supervisor
  N9K-C9232C:
    model: N9K-C9232C
    manufacturer: cisco
    u_height: 1
    comments: 32x40/100G QSFP28 Ethernet Module
  N3K-C3264C-E:
    model: N3K-C3264C-E
    manufacturer: cisco
    u_height: 1
    comments: 64x100G QSFP28 + 2x10G SFP+ Ethernet
  N9K-C93108TC-FX:
    model: N9K-C93108TC-FX
    manufacturer: cisco
    u_height: 1
  N9K-C93180YC-EX:
    model: N9K-C93180YC-EX
    manufacturer: cisco
    u_height: 1
    comments: 48x10/25G + 6x40/100G Ethernet Module
  N9K-C93600CD-GX:
    model: N9K-C93600CD-GX
    manufacturer: cisco
    u_height: 1
  N9K-C9316D-GX:
    model: N9K-C9316D-GX
    manufacturer: cisco
    u_height: 1
  N9K-C9336C-FX2:
    model: N9K-C9336C-FX2
    manufacturer: cisco
    u_height: 1
    comments: 36x40/100G QSFP28 Ethernet Module
  N9K-C9348GC-FXP:
    model: N9K-C9348GC-FXP
    manufacturer: cisco
    u_height: 1
  N9K-C9364D-GX2A:
    model: N9K-C9364D-GX2A
    manufacturer: cisco
    u_height: 1
    comments: 64x400G QSFP-DD + 2x10G SFP+ Ethernet Module, Duval
  N9K-C9504:
    model: N9K-C9504
    manufacturer: cisco
    u_height: 7
    comments: Nexus9000 C9504 (4 Slot) Chassis
  SPT-N11U:
    model: SPT-N11U
    manufacturer: spirent
    u_height: 11
  SPT-N12U:
    model: SPT-N12U
    manufacturer: spirent
    u_height: 12
    comments: Spirent 12U 400G Appliance
  UCS-C210-M2:
    model: UCS-C210-M2
    manufacturer: cisco
    u_height: 2
  UCSC-C220-M6S:
    model: UCSC-C220-M6S
    manufacturer: cisco
    u_height: 1

# Device Roles
# Mandatory keys:
#   name: Name of the role
#   color: Use one of the color choices from the top of this file
#
# Optional keys
#   description : free-form description
#   tags: yaml list of tags. Tags must already be present in Netbox.
device_roles:
  ipam_dcim:
    name: ipam_dcim
    color: gray
    description: ip address management and data center infra management
    tags:
      - infra
  lab_gateway:
    name: lab_gateway
    color: gray
    description: lab mgmt vlan gateways
    tags:
      - infra
  lab_tor:
    name: lab_tor
    color: gray
    description: lab mgmt vlan L2 tor
    tags:
      - infra
  mgmt:
    name: mgmt
    color: gray
    description: top of rack L2 switches for management vlans
    tags:
      - infra
  na:
    name: na
    color: gray_light
    description: Roles are not applicable to this device
  terminal_server:
    name: terminal_server
    color: gray
    description: console port connectivity
  traffic_generator:
    name: traffic_generator
    color: purple
    tags:
      - tgen
  unknown:
    name: unknown
    color: gray_dark
    description: unknown role for device
  vm_host:
    name: vm_host
    color: gray_light
    description: bare metal servers hosting virtual machines

# Console Ports
# Mandatory keys
#   device: Name of the device that contains this port
#   port: Name of the port
#
# Optional keys
#   description: Free-form description for the Console Port
#   label: The text for a physical label affixed to the console_port
#   mark_connected: boolean. Treat as if a cable is connected
#   port_speed: speed in kbps of the console port. Valid values: 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200
#   port_type: type of port. Valid values: de-9, db-25, rj-11, rj-12, rj-45, mini-din-8, usb-a, usb-b, usb-c, 
#                                          usb-mini-a, usb-mini-b, usb-micro-a, usb-micro-b, usb-micro-ab, other
#   tags: A YAML list of tags to associate with the Console Port to enable filtering based on tag.
console_ports:
  lab_gateway_167_1_console:
    description: lab_gateway_167_1_console
    device: lab_gateway_167_1
    label: dc_115
    port: console
    port_speed: 9600
    port_type: rj-45
    tags:
      - admin
      - infra

# Console Server Ports
# Mandatory keys
#   device: Name of the device that contains this port
#   port: Name of the port
#
# Optional keys
#   description: Free-form description for the Console Server Port
#   label: The text for a physical label affixed to the console_server_port
#   mark_connected: boolean. Treat as if a cable is connected
#   port_speed: speed in kbps of the console port. Example valid values: 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200
#   port_type: type of port. Example valid values: de-9, db-25, rj-11, rj-12, rj-45, mini-din-8, usb-a, usb-b, usb-c, 
#                                          usb-mini-a, usb-mini-b, usb-micro-a, usb-micro-b, usb-micro-ab, other
#   tags: A YAML list of tags to associate with the Console Server Port to enable filtering based on tag.

console_server_ports:
  ts_1_2003:
    device: ts_1
    label: dc_115
    port: 2003
    port_speed: 9600
    port_type: rj-45
    description: bgw_3
    tags:
      - admin

# Devices
# Mandatory keys
#   device: Name of the device
#   site: The site in which the device is located (could be a fabric name, testbed, or physical location, etc)
#   interface: A pointer to the interface used to manage the device. 
#              The pointer is a key name in the interfaces dictionary in this file.
#        For example, if the following is used as the management interface:
#           interface: cvd_leaf_1_mgmt0
#        We must have something like the following in the interfaces section
#        interfaces:
#           cvd_leaf_1_mgmt0:
#             interface: mgmt0
#             mgmt_only: True
#             mac_address: 0000.014f.ffde
#             etc...
#   role: The device's functional role e.g. spine.
#   type: The hardware device type which defines the device's make & model.
#
# Optional keys
#   cluster: the virtualization cluster that VMs in this device belong to (see clusters section)
#   interface_type: The type of interface (pertains to mgmt0). If not present, mgmt0 interface_type defaults
#                   to 1000base-t
#   mac_address: The mac address of the interface e.g. from 'show interface mgmt0'
#   rack: The rack in which device resides (rack must be present in racks section of this file)
#   position: The bottom-most position (RU) in the rack that the device occupies (e.g. for a 3-RU
#             unit taking spaces 1-3, you would list 1 as the position).  If rack is specified,
#             position must also be specified.
#   face: The rack face the device is installed in. Valid values: front, rear
#   serial: The serial number of the device e.g. from 'show module'
#   tags: A YAML list of tags to associate with the device to enable filtering based on tag.
# NOTES
# 1. role. This must match an entry in device_roles section.
#          Use 'unknown' if you don't know the role
#          Use 'na' if the role is not applicable
# 2. type. This must match an entry in device_types section.
# 3. tags. All tags must be listed in the tags section of this file.  We could have written the
#          scripts to create tags "on demand" if they are added to a device below but are not 
#          present in netbox, but that would likely result in "tag explosion."  Instead, we 
#          opted to force the user to think about why they aspeedre adding a tag by requiring that
#          all tags be listed in the tags section. This also forces you to document all your
#          tags in a single place.

devices:
  lab_gateway_167_1:
    device: lab_gateway_1
    interface: lab_gateway_167_1_mgmt0
    role: lab_gateway
    type: CISCO-UNKNOWN
    serial: na
    site: mysite
    tags:
      - infra
  vm_host_1:
    device: vm_host_1
    interface: vm_host_1_eth1
    role: vm_host
    cluster: db
    type: UCSC-C220-M6S
    serial: na
    site: mysite
    tags:
      - infra

# Interfaces
# Mandatory keys
#   device: Name of the device that contains this interface
#   interface: Name of the interface e.g. Ethernet1/1
# Optional keys
#   description: Free-form description for the Console Server Port
#   interface_enabled: True or False.  If True, interface is enabled.  If False, interface is disabled.
#   interface_mode: Mode of the interface.  Valid values: access, tagged, tagged-all
#   interface_type: PHY type of the interface. Common values: 1000base-t, 10gbase-t, 1000base-x-sfp.  See Netbox docs for full list.
#   ip4: The ipv4 address, if any, of the interface. (See NOTE 2 below)
#   mac_address: The mac address of the interface.
#   mgmt_only: True or False. If True, the interface is used only for device management.
#   mtu: Maximum transfer unit, in bytes, of the interface
#   untagged_vlan: Vlan ID for access mode interfaces
#
# NOTES:
# 1. The dictionary key for each interface below is used as the value for 'interface'
#    in the devices: section above.  Below, the keys are 'lab_gateway_167_1_mgmt0' 
#    and 'vm_host_1_eth1' and these match the values for the 'interface' key for 
#    devices 'cvd_leaf_1' and 'vm_host_1', respectively, in the devices section above
# 2. ip4. This field is used by the scripts and libraries in this repo either directly
#    i.e. as an ipv4 address with mask, or as a pointer into the ip4_addresses dictionary.
#    If the ip4 value exists as a key in the ip4_addresses dictionary, the entry
#    is used to supply the optional values, if any, associated with the ip4 address.
#    Currently these are "role" and "status".
interfaces:
  lab_gateway_167_1_mgmt0:
    device: cvd_leaf_1
    interface: mgmt0
    ip4: 192.168.1.1/24
    interface_mode: access
    interface_type: 1000base-t
    mac_address: 00a3.8ebf.eaf6
    mgmt_only: True
  vm_host_1_eth1:
    device: vm_host_1
    interface: eth1
    ip4: 192.168.1.2/24
    interface_mode: access
    interface_type: 1000base-t
    mac_address: 00a3.66b4.f8aa
    mgmt_only: True
  tor_1_eth1_1:
    device: tor_1_eth1
    interface: Ethernet1/1
    ip4: 192.168.1.3/24
    interface_mode: access
    interface_type: 1000base-t
    mac_address: 00fa.dec3.1dba
    mgmt_only: False

#ip4_addresses
# This is where we set the optional Netbox values (currently role and status)
# for ipv4 addresses.
# keyed on ipv4 address with mask e.g. A.B.C.D/E
# In the interfaces dictionary, elsewhere in this file, the ip4 field
# is used as either:
#   - A direct ip address/mask value, if the value in the ip4 field
#     does not appear as a key in the ip4_addresses dictionary below.
#   - A key into the ip4_addresses dictionary, if the value of the ip4
#     field DOES appear as a key in the ip4_addresses dictionary below.
# Mandatory fields
# ip4 - the ipv4 address with mask e.g. A.B.C.D/E
# Optional fields
# role: one of [loopback, secondary, anycast, vip, vrrp, hsrp, glbp, carp]
# status: one of [active, reserved, deprecated, dhcp, slaac]
ip4_addresses:
  192.168.1.1/24:
    ip4: 192.168.1.1/24
    status: active
  192.168.1.2/24:
    ip4: 192.168.1.2/24
    role: vip
    status: deprecated

cables:
  tor_1_eth1_1__vm_host_1_eth1:
    label: tor_1_eth1_1__vm_host_1_eth1
    cable_type: cat5e
    color: red
    length: 5
    length_unit: m
    port_a: tor_1_eth1_1   # pointer to an interface in interfaces above
    port_b: vm_host_1_eth1 # pointer to an interface in interfaces above
    tags:
      - admin
      - yoda


# clusters
# Mandatory fields
#   cluster: (str) The name of the cluster
#   type: (str) pointer to item in cluster_types dictionary
#   group: The cluster_group that contains the cluster. Mutually-exclusive with site. (NOT YET SUPPORTED)
#   site: The site that contains the cluster.  Mutually-exclusive with group.
# Optional fields
#   description: (str) free-form description of the cluster type
#   tags: YAML list of tags to allow later searching by tag
clusters:
  db:
    cluster: db
    type: vmware
    # group: db_servers
    site: mysite

# cluster_types
# Mandatory fields
#   name: (str) The name of the cluster type
# Optional fields
#   description: (str) free-form description of the cluster type
#   tags: YAML list of tags to allow later searching by tag
cluster_types:
  vmware:
    name: vmware
    description: VMWare cluster
    tags:
      - admin

# virtual_machines
# Mandatory fields
#   vm: (str) The name of the virtual machine
#   cluster: (str) The cluster in which the virtual machine is located *
#      If cluster is defined, site will be taken from cluster
#   site: (str) The site in which the virtual machine is located *
#      If cluster is not defined, site can be specified directly
# Optional fields
#   device: (str) Device hosting the vm *
#   memory: (int) Memory allocated to the virtual machine, in MB
#   primary_ip4: (ipv4/prefix) IPv4 address of the vm *
#   role: (str) Role the vm serves *
#   status: (str) One of: offline, active, planned, staged, failed, decommissioning
#   tenent: (str) Tenent to which vm is assigned *,+
#   vcpus: (float) Number of virtual cpu units. Min 0.01
#  * Item must be present in netbox
#  + Not currently supported
virtual_machines:
  netbox_vm:
    vm: netbox
    site: mysite
    device: vm_host_1
    role: ipam_dcim
    memory: 4000
    interface: netbox_vm_vmnet0
    vcpus: 4
    tags:
      - admin
      - infra

# virtual_interfaces
# Mandatory fields:
#    virtual_machine
#    interface:
# Optional fields:
#   description       str - freeform description of the interface
#   ip4               ipv4 address with prefix e.g. A.B.C.D/E
#   interface_enabled bool - interface administrative state enabled?  True/False
#   interface_mode    str - access, tagged, tagged-all
#   mac_address       str - xxxx.xxxx.xxxx, xx:xx:xx:xx:xx:xx
#   untagged_vlan     int - 
#   
virtual_interfaces:
  netbox_vm_vmnet0:
    virtual_machine: netbox_vm
    interface: vm0
    ipv4: 192.168.1.4/24
    interface_mode: access

# VlanGroup
# Mandatory fields
#   vlan_group: The vlan group name
# Optional fields
#   min_vid: Minimum vlan id for this VlanGroup
#   max_vid: Maximum vlan id for this VlanGroup
#   description: Free-form description for this VlanGroup
#   tags: A YAML list of tags to associate with the VlanGroup to enable filtering based on tag.
vlan_groups:
  AdminServers:
    vlan_group: AdminServers
    min_vid: 2
    max_vid: 16
    description: Administration Servers
    tags:
      - admin
      - infra

# Vlans
# Mandatory fields
#   vlan_name: The vlan name
#   vid: The vlan ID, aka vid, of the vlan
# Optional fields
#   description: Free-form description for the vlan
#   group: The vlan_group the vlan belongs to.  Must already exist in Netbox. See vlan_groups above. Mutually-exclusive with site.
#   role: The role the vlan serves
#   site: The site that contains the vlan.  Mutually-exclusive with group.
#   status: The status of the vlan. Valid values: active, reserved, deprecated
#   tags: YAML list of tags to associate with the vlan
#
# NOTES:
#   1. group and site are mutually-exclusive.  If one is set, the other cannot be set.
vlans:
  Vlan10:
    vlan_name: WebServers
    vid: 10
    site: mysite
    status: active
  Vlan20:
    vlan_name: DBServers
    vid: 20
    group: AdminServers
    status: active
    tags:
      - admin