Инвентаризация netbox.netbox.nb_inventory – источник инвентаризации NetBox

Примечание

Этот плагин инвентаризации входит в коллекцию netbox.netbox (версия 3.22.0).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в состав ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Чтобы установить её, используйте: ansible-galaxy collection install netbox.netbox.

Чтобы использовать её в плейбуке, укажите: netbox.netbox.nb_inventory.

Краткое описание
Параметры
Примечания
Примеры

Краткое описание

Получение узлов инвентаризации из NetBox

Параметры

Параметр	Комментарии
ansible_host_dns_name boolean	Если True, в переменной ansible_host вместо IP-адреса будет использоваться DNS-имя (полученное из primary_ip). Варианты: `false` ← (по умолчанию) `true`
api_endpoint string / обязательный	Конечная точка API NetBox Конфигурация: Переменная среды: `NETBOX_API`
ca_path string	Путь к CA По умолчанию: `false`
cache boolean	Включает или отключает кэширование исходных данных инвентаризации; для работы требуется настроенный плагин кэширования. Варианты: `false` ← (по умолчанию) `true` Конфигурация: Запись INI: [inventory] cache = false Переменная среды: `ANSIBLE_INVENTORY_CACHE`
cache_connection string	Данные подключения к кэшу или путь к нему; подробности см. в документации плагина кэширования. Конфигурация: Записи INI: [defaults] fact_caching_connection = VALUE [inventory] cache_connection = VALUE Переменная среды: `ANSIBLE_CACHE_PLUGIN_CONNECTION` Переменная среды: `ANSIBLE_INVENTORY_CACHE_CONNECTION`
cache_plugin string	Плагин кэширования исходных данных инвентаризации. По умолчанию: `"memory"` Конфигурация: Записи INI: [defaults] fact_caching = memory [inventory] cache_plugin = memory Переменная среды: `ANSIBLE_CACHE_PLUGIN` Переменная среды: `ANSIBLE_INVENTORY_CACHE_PLUGIN`
cache_prefix string	Префикс для файлов и таблиц плагина кэширования. По умолчанию: `"ansible_inventory_"` Конфигурация: Записи INI: [defaults] fact_caching_prefix = ansible_inventory_ [inventory] cache_prefix = ansible_inventory_ Переменная среды: `ANSIBLE_CACHE_PLUGIN_PREFIX` Переменная среды: `ANSIBLE_INVENTORY_CACHE_PLUGIN_PREFIX`
cache_timeout integer	Длительность кэширования в секундах. По умолчанию: `3600` Конфигурация: Записи INI: [defaults] fact_caching_timeout = 3600 [inventory] cache_timeout = 3600 Переменная среды: `ANSIBLE_CACHE_PLUGIN_TIMEOUT` Переменная среды: `ANSIBLE_INVENTORY_CACHE_TIMEOUT`
cert string	Путь к сертификату По умолчанию: `false`
compose dictionary	Список пользовательских переменных узла Ansible, создаваемых на основе объекта устройства, полученного из NetBox По умолчанию: `{}`
config_context boolean	Если True, добавляет config_context в переменные узла. Контекст конфигурации позволяет связывать произвольные данные с устройствами и виртуальными машинами, сгруппированными по региону, площадке, роли, платформе и/или арендатору. Дополнительные сведения см. в официальной документации NetBox. Варианты: `false` ← (по умолчанию) `true`
device_query_filters list / elements=string	Список параметров, передаваемых в строку запроса для устройств (несколько значений можно разделять запятыми). Также можно использовать шаблоны Jinja2. По умолчанию: `[]`
dns_name boolean	Принудительно получать IP-адреса, чтобы dns_name для primary_ip каждого устройства или виртуальной машины устанавливался как host_var. При включении интерфейсов также будут получены IP-адреса и задана переменная dns_name. Варианты: `false` ← (по умолчанию) `true`
fetch_all boolean добавлено в netbox.netbox 0.2.1	По умолчанию при получении интерфейсов и служб загружаются все данные из NetBox независимо от query_filters, применённых к устройствам и виртуальным машинам. Если установлено значение False, для каждого device_id и virtual_machine_id будут отправляться отдельные запросы для получения интерфейсов, служб и IP-адресов. Если вы используете различные параметры query_filters для сокращения числа устройств, запросы к NetBox могут выполняться быстрее, если установить fetch_all в False. Для повышения эффективности при значении False запросы объединяются в пакеты, например /api/dcim/interfaces?limit=0&device_id=1&device_id=2&device_id=3 Для большого числа устройств URI GET-запросов могут стать очень длинными. Если вы столкнулись с ошибками HTTP 414, настройте параметр max_uri_length в соответствии с используемым веб-сервером. Варианты: `false` `true` ← (по умолчанию)
flatten_config_context boolean добавлено в netbox.netbox 0.2.1	Если включён config_context, по умолчанию он добавляется как переменная узла с именем config_context. Если для flatten_config_context задано значение True, переменные контекста конфигурации будут добавлены непосредственно к узлу. Варианты: `false` ← (по умолчанию) `true`
flatten_custom_fields boolean добавлено в netbox.netbox 0.2.1	По умолчанию пользовательские поля узла добавляются в виде словаря — переменной узла с именем custom_fields. Если для flatten_custom_fields задано значение True, поля будут добавлены непосредственно к узлу. Варианты: `false` ← (по умолчанию) `true`
flatten_local_context_data boolean добавлено в netbox.netbox 0.3.0	Если включён local_context_data, по умолчанию он добавляется как переменная узла с именем local_context_data. Если для flatten_local_context_data задано значение True, переменные контекста конфигурации будут добавлены непосредственно к узлу. Варианты: `false` ← (по умолчанию) `true`
follow_redirects string	Определяет способ обработки перенаправлений. По умолчанию для follow_redirects используется поведение urllib2 по умолчанию. Варианты: `"urllib2"` ← (по умолчанию) `"all"` `"yes"` `"safe"` `"none"`
group_by list / elements=string	Ключи, используемые для создания групп. Параметры plurals и racks определяют, какие из них допустимы. rack_group поддерживается только в NetBox версии 2.10 или более ранней location поддерживается только в NetBox версии 2.11 или более поздней Варианты: `"sites"` `"site"` `"location"` `"tenants"` `"tenant"` `"racks"` `"rack"` `"rack_group"` `"rack_role"` `"tags"` `"tag"` `"device_roles"` `"role"` `"device_types"` `"device_type"` `"manufacturers"` `"manufacturer"` `"platforms"` `"platform"` `"region"` `"site_group"` `"cluster"` `"cluster_type"` `"cluster_group"` `"is_virtual"` `"services"` `"status"` `"time_zone"` `"utc_offset"` `"facility"` По умолчанию: `[]`
group_names_raw boolean добавлено в netbox.netbox 0.2.0	Не добавлять название варианта group_by к названиям групп Варианты: `false` ← (по умолчанию) `true`
groups dictionary	Добавлять узлы в группы на основе условий Jinja2. По умолчанию: `{}`
headers string	Словарь заголовков, передаваемых в API NetBox. По умолчанию: `{}` Конфигурация: Переменная среды: `NETBOX_HEADERS`
hostname_field string	По умолчанию имя узла в инвентаризации совпадает с именем устройства в NetBox Если задано, имя узла в инвентаризации берётся из этого поля в custom_fields По умолчанию: `false`
interfaces boolean добавлено в netbox.netbox 0.1.7	Если True, добавляет сведения об интерфейсах устройства или виртуальной машины в переменные узла. Варианты: `false` ← (по умолчанию) `true`
key string	Путь к ключу сертификата По умолчанию: `false`
keyed_groups list / elements=dictionary	Добавлять узлы в группы на основе значений переменной. По умолчанию: `[]`
default_value string добавлено в ansible-core 2.12	Значение по умолчанию, если значение переменной узла равно `None` или является пустой строкой. Этот параметр несовместим с `keyed_groups[].trailing_separator`.
key string	Ключ входного словаря, используемый для создания групп.
parent_group string	Родительская группа для группы по ключу.
prefix string	Название группы по ключу будет начинаться с этого префикса. По умолчанию: `""`
separator string	Разделитель, используемый для формирования названия группы по ключу. По умолчанию: `"_"`
trailing_separator boolean добавлено в ansible-core 2.12	Установите для этого параметра значение `false`, чтобы не добавлять `keyed_groups[].separator` после переменной узла, если её значение равно `None` или является пустой строкой. Этот параметр несовместим с `keyed_groups[].default_value`. Варианты: `false` `true` ← (по умолчанию)
leading_separator boolean добавлено в ansible-core 2.11	Используется вместе с `keyed_groups`. По умолчанию название группы по ключу, для которой не задан префикс или разделитель, начинается с символа подчёркивания. Это связано с тем, что префикс по умолчанию — `""`, а разделитель по умолчанию — `"_"`. Установите для этого параметра значение `false`, чтобы не добавлять символ подчёркивания в начале (или другой разделитель), если префикс не задан. Если название группы формируется из соответствия, разделитель всё равно используется для объединения элементов. Чтобы вообще не использовать разделитель в названии группы, задайте для группы по ключу пустую строку в качестве разделителя. Варианты: `false` `true` ← (по умолчанию)
max_uri_length integer добавлено в netbox.netbox 0.2.1	Если fetch_all имеет значение False, GET-запросы к NetBox могут стать очень длинными и приводить к ошибке HTTP 414 (URI Too Long). Чтобы избежать ошибок 414, можно уменьшить значение этого параметра; чтобы сократить количество запросов — увеличить его. По умолчанию: `4000`
oob_ip_as_primary_ip boolean	Использовать внеполосный IP-адрес в качестве `ansible host` Варианты: `false` ← (по умолчанию) `true`
plugin string / обязательный	Токен, подтверждающий, что это файл источника для плагина ‘netbox’. Варианты: `"netbox.netbox.nb_inventory"`
plurals boolean добавлено в netbox.netbox 0.2.1	Если True, все переменные узла помещаются в массивы из одного элемента для обратной совместимости со старыми версиями этого плагина. Названия групп будут использовать множественное число (например, “sites_mysite” вместо “site_mysite”) Этот параметр изменяет варианты group_by. Варианты: `false` `true` ← (по умолчанию)
prefixes boolean добавлено в netbox.netbox 3.5.0	Если True, добавляет префиксы устройства или виртуальной машины во вложенные в “site” переменные hostvars. Выбор должен совпадать с параметром “site_data”, так как он изменяет структуру “site” в hostvars Варианты: `false` ← (по умолчанию) `true`

query_filters list / elements=string	Список параметров, передаваемых в строку запроса для устройств и виртуальных машин (несколько значений можно разделять запятыми). Также можно использовать шаблоны Jinja2. По умолчанию: `[]`
racks boolean добавлено в netbox.netbox 3.6.0	Если False, пропустить запрос сведений о стойках, который может выполняться медленно при большом количестве стоек. Этот параметр изменяет доступные варианты group_by. Варианты: `false` `true` ← (по умолчанию)
rename_variables list / elements=dictionary	Переименовывает переменные, вычисленные nb_inventory, перед их записью. Каждый элемент списка содержит словарь с параметрами ‘pattern’ и ‘repl’. И ‘pattern’, и ‘repl’ — регулярные выражения. Используется первое совпавшее выражение, последующие совпадения игнорируются. Внутри используется `re.sub`. По умолчанию: `[]`
services boolean добавлено в netbox.netbox 0.2.0	Если True, добавляет сведения о службах устройства или виртуальной машины в переменные хоста. Варианты: `false` `true` ← (по умолчанию)
site_data boolean добавлено в netbox.netbox 3.5.0	Если True, полные структуры данных площадок, полученные от API Netbox, включаются в переменные хоста. Варианты: `false` ← (по умолчанию) `true`
strict boolean	Если `yes`, считать недопустимые записи фатальной ошибкой; в противном случае пропустить их и продолжить выполнение. Поскольку в выражениях можно использовать факты, они могут быть доступны не всегда; по умолчанию такие ошибки игнорируются. Варианты: `false` ← (по умолчанию) `true`
timeout integer	Тайм-аут запросов к NetBox в секундах По умолчанию: `60`
token string	Токен API NetBox для чтения данных из NetBox. В зависимости от конфигурации NetBox он может не требоваться. Если в вашем развертывании NetBox используется более сложная аутентификация, например OAUTH, для токена можно указать “type” и “value”. Если параметры “type” и “value” не указаны, для заголовка авторизации HTTP будет установлено значение “Token”, используемое в NetBox по умолчанию. Конфигурация: Переменная окружения: `NETBOX_TOKEN` Переменная окружения: `NETBOX_API_KEY`
use_extra_vars boolean добавлено в ansible-core 2.11	Объединять дополнительные переменные с доступными переменными для композиции (наивысший приоритет). Варианты: `false` ← (по умолчанию) `true` Конфигурация: Запись INI: [inventory_plugins] use_extra_vars = false Переменная окружения: `ANSIBLE_INVENTORY_USE_EXTRA_VARS`
validate_certs boolean	Разрешает подключение, если сертификаты SSL недействительны. Установите значение `false`, если сертификаты не являются доверенными. Варианты: `false` `true` ← (по умолчанию)
virtual_chassis_name boolean	Если устройство входит в виртуальное шасси, использовать имя виртуального шасси в качестве имени узла в инвентаре Ansible. Значения переменных хоста будут взяты у ведущего устройства виртуального шасси. Варианты: `false` ← (по умолчанию) `true`
virtual_disks boolean добавлено в netbox.netbox 3.18.0	Если True, добавляет сведения о виртуальных дисках в переменные хоста. Варианты: `false` ← (по умолчанию) `true`
vm_query_filters list / elements=string	Список параметров, передаваемых в строку запроса для виртуальных машин (несколько значений можно разделять запятыми). Также можно использовать шаблоны Jinja2. По умолчанию: `[]`

Примечание

Перечисленные выше для каждого типа записи параметры конфигурации (переменная Ansible, переменная окружения и т. д.) имеют приоритет от низкого к высокому. Например, переменная, расположенная ниже в списке, переопределяет переменную, расположенную выше. Типы записей также упорядочены по возрастанию приоритета. Например, запись в ansible.cfg (расположенная выше в списке) переопределяется переменной Ansible (расположенной ниже в списке).

Примечания

Примечание

На этом этапе инвентари ещё не окончательно сформированы, поэтому автоматически заполняемые группы all и ungrouped будут содержать только те данные, которые явно добавили в них предыдущие источники инвентаря.
«Магические переменные» времени выполнения недоступны во время построения инвентаря. Например, groups и hostvars ещё не существуют.

Примеры

# netbox_inventory.yml file in YAML format
# Example command line: ansible-inventory -v --list -i netbox_inventory.yml

plugin: netbox.netbox.nb_inventory
api_endpoint: http://localhost:8000
validate_certs: true
config_context: false
group_by:
  - device_roles
query_filters:
  - role: network-edge-router
device_query_filters:
  - has_primary_ip: 'true'
  - tenant__n: internal
headers:
  Cookie: "{{ auth_cookie }}"

# has_primary_ip is a useful way to filter out patch panels and other passive devices
# Adding '__n' to a field searches for the negation of the value.
# The above searches for devices that are NOT "tenant = internal"

# Query filters are passed directly as an argument to the fetching queries.
# You can repeat tags in the query string.

query_filters:
  - role: server
  - tag: web
  - tag: production

# See the NetBox documentation at https://netbox.readthedocs.io/en/stable/rest-api/overview/
# the query_filters work as a logical **OR**
#
# Prefix any custom fields with cf_ and pass the field value with the regular NetBox query string

query_filters:
  - cf_foo: bar

# NetBox inventory plugin also supports Constructable semantics
# You can fill your hosts vars using the compose option:

plugin: netbox.netbox.nb_inventory
compose:
  foo: last_updated
  bar: display_name
  nested_variable: rack.display_name

# You can use keyed_groups to group on properties of devices or VMs.
# NOTE: It's only possible to key off direct items on the device/VM objects.
plugin: netbox.netbox.nb_inventory
keyed_groups:
  - prefix: status
    key: status.value

# For use in Ansible Tower (AWX) the credential for NetBox will need to expose NETBOX_API
# and NETBOX_TOKEN as environment variables.
# Example Ansible Tower credential Input Configuration:

fields:
  - id: NETBOX_API
    type: string
    label: NetBox Host URL
  - id: NETBOX_TOKEN
    type: string
    label: NetBox API Token
    secret: true
required:
  - NETBOX_API
  - NETBOX_TOKEN

# Example Ansible Tower credential Injector Configuration:

env:
  NETBOX_API: '{{ NETBOX_API }}'
  NETBOX_TOKEN: '{{ NETBOX_TOKEN }}'

# Example of time_zone and utc_offset usage

plugin: netbox.netbox.nb_inventory
api_endpoint: http://localhost:8000
token: <insert token>
validate_certs: true
config_context: true
group_by:
  - site
  - role
  - time_zone
  - utc_offset
device_query_filters:
  - has_primary_ip: 'true'
  - manufacturer_id: 1

# using group by time_zone, utc_offset it will group devices in ansible groups depending on time zone configured on site.
# time_zone gives grouping like:
# - "time_zone_Europe_Bucharest"
# - "time_zone_Europe_Copenhagen"
# - "time_zone_America_Denver"
# utc_offset gives grouping like:
# - "time_zone_utc_minus_7"
# - "time_zone_utc_plus_1"
# - "time_zone_utc_plus_10"

# Example of using a token type

plugin: netbox.netbox.nb_inventory
api_endpoint: http://localhost:8000
token:
  type: Bearer
  value: test123456

Авторы

Remy Leone (@sieben)
Anthony Ruhier (@Anthony25)
Nikhil Singh Baliyan (@nikkytub)
Sander Steffann (@steffann)
Douglas Heriot (@DouglasHeriot)
Thore Knickrehm (@tkn2023)

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/netbox/netbox/nb_inventory_inventory.html