lae.netbox

Descripción general Versiones Perspectivas

:role-author: lae
:role-name: netbox
:role: {role-author}.{role-name}
:gh-name: {role-author}/ansible-role-{role-name}
:netbox-version: 3.7.3
= {role}
:toc:
:toc-placement: preamble
ifdef::env-github[]
:tip-caption: :bulb:
:warning-caption: :warning:
endif::[]

ifdef::env-github[]
image:https://img.shields.io/badge/role-{role}-blue?style=for-the-badge[Ansible Galaxy Role,link=https://galaxy.ansible.com/{role-author}/{role-name}]
endif::env-github[]

Despliega y configura https://github.com/netbox-community/netbox[NetBox], una herramienta de gestión de direcciones IP (IPAM) y de gestión de infraestructura de centros de datos (DCIM).

Este rol desplegará NetBox en su propio entorno virtual, ya sea a través de un archivo tar de la versión o mediante git, utilizando uWSGI como el servidor de aplicaciones.

Es compatible con CentOS 7, 8 / RHEL 9 / Debian 9, 10, 11, 12 / Ubuntu 16, 18, 20 y 22.

Nota que este rol tiene algunas opiniones y se diferencia de las instrucciones de instalación de la documentación de NetBox. Las principales diferencias son:

  • Usa systemd proporcionado por la distribución en lugar de supervisord
  • Utiliza uWSGI como servidor de aplicaciones en lugar de gunicorn
  • Refuerza el servicio de NetBox/uWSGI (ver templates/netbox.service.j2)
  • Recargará en caliente durante actualizaciones y cambios de configuración

== Introducción Rápida

Si tienes Ansible instalado y utilizas los valores por defecto:

[source,bash,subs="attributes"]

ansible-galaxy install geerlingguy.postgresql davidwittman.redis {role}
ansible-galaxy collection install community.postgresql
ansible-playbook -i your.server.fqdn, ~/.ansible/roles/{role}/examples/playbook_single_host_deploy.yml -K

Esto desplegará NetBox y PostgreSQL en your.server.fqdn; una vez completado, debería ser accesible en el puerto 80. Modifica si es necesario. Lee más abajo para más información.

También puedes usar Vagrant, si lo prefieres, para iniciar NetBox en localhost:8080:

[source,bash,subs="attributes"]

ansible-galaxy install geerlingguy.postgresql davidwittman.redis {role}
ansible-galaxy collection install community.postgresql
cd ~/.ansible/roles/{role}/
vagrant up

== Soporte / Contribución

Si deseas contribuir a este rol, por favor, lee DEVELOPING.md para conocer el flujo de trabajo de este repositorio y las instrucciones (opcionales) para configurar un entorno de desarrollo. Este rol utiliza el rol lae.travis-lxc al probar en Travis CI, que puedes encontrar en el directorio tests/.

ifeval::["{role-author}" == "lae"]
Para soporte o si deseas contribuir a este rol pero necesitas orientación, siéntete libre de preguntar en el servidor de Discord de @lae: https://discord.gg/cjqr6Fg
endif::[]

== Requisitos

=== PostgreSQL

Este rol no configura un servidor PostgreSQL (pero creará una base de datos si es necesario), así que necesitarás configurar un servidor PostgreSQL y crear un usuario de base de datos por separado de este rol. Echa un vistazo en la sección Ejemplo de Playbook.

Además, para Ansible 2.10+, puede que necesites instalar la colección community.postgresql. Se recomienda especificar esto en el archivo requirements.yml de tu playbook. Por ejemplo:

[source,yaml]

collections:

  • name: community.postgresql
    version: 3.4.0

ADVERTENCIA: NetBox v2.2.0+ requiere al menos PostgreSQL 9.4, que puede no estar disponible en los repositorios de tu distribución. Puede que desees usar un rol para esto.

=== Redis

Este rol no configura ni administra una instancia de Redis. Puede que desees instalar redis-server a través de una tarea en pre_tasks dentro de tu playbook o usar un rol de instalación de Redis como https://galaxy.ansible.com/davidwittman/redis[DavidWittman.redis].

ADVERTENCIA: NetBox v2.9.0+ requiere al menos Redis 4.0. El rol sugerido anteriormente predetermina a una versión 2.8, así que asegúrate de especificar una versión más nueva en una variable de rol o desplegar Redis 4.0+ de otra manera.

== Variables del Rol

CONSEJO: Consulta examples/ para algunos playbooks que podrías escribir para diferentes escenarios.

ADVERTENCIA: Algunas variables del rol son obligatorias. Busca el requerido en negrita a continuación.

[source,yaml]

netbox_stable: false
netbox_git: false

Es requerido establecer una de las variables anteriores en true. netbox_stable indica al rol que despliegue extrayendo archivos tar de las versiones de GitHub, mientras que netbox_git indica al rol que clone un repositorio git de NetBox; son mutuamente excluyentes.

[source,yaml,subs="attributes"]

netbox_stable_version: {netbox-version}
netbox_stable_uri: "https://github.com/netbox-community/netbox/archive/v{{ netbox_stable_version }}.tar.gz"

Estas se pueden configurar para fijar una versión (por ejemplo, aumentar para activar una actualización) o desplegar usando un tar ubicado en otro lugar. Útil cuando necesitas modificar algo en una versión o estás desplegando localmente detrás de un firewall.

[source,yaml]

netbox_git_version: develop
netbox_git_uri: "https://github.com/netbox-community/netbox.git"

netbox_git_version puede ser cualquier referencia válida dentro de un repositorio git. netbox_git_uri se puede usar para apuntar a un repositorio interno o a un fork.

[source,yaml]

netbox_superuser_enabled: true
netbox_superuser_username: admin
#netbox_superuser_password: changeme
netbox_superuser_email: admin@localhost
netbox_superuser_create_token: false

Estas variables se utilizan para configurar una cuenta local de superusuario. Desactiva esto si no quieres crear una (cuando usas LDAP, por ejemplo, aunque tener un superusuario local puede seguir siendo beneficioso en ese caso). Cuando se activa, es requerido establecer la contraseña del superusuario. Este rol creará un nuevo superusuario si el usuario no existe, o modificará un usuario existente si no es superusuario/tiene un correo electrónico o contraseña diferentes. (Sí, puedes usar esto para restablecer tu contraseña de superusuario si la olvidas). netbox_superuser_create_token se puede usar para generar un token API aleatorio para el superusuario, si es necesario.

[source,yaml]

netbox_database: netbox
netbox_database_user: netbox
#netbox_database_password: changeme
#netbox_database_host: localhost
netbox_database_port: 5432
#netbox_database_socket: /var/run/postgresql

Es requerido configurar ya sea un directorio de socket (para comunicarse a través de sockets UNIX) o un host/contraseña (para usar TCP/IP). Consulta la sección Ejemplo de Playbook para más información sobre cómo configurar la base de datos.

Ten en cuenta que estas se utilizan para configurar DATABASE en configuration.py.

[source,yaml]

netbox_database_conn_age: 300

Para configurar NetBox a mantener conexiones de base de datos abiertas más tiempo que una sola solicitud, establece netbox_database_conn_age en tu edad máxima de conexión preferida, en segundos. 300 segundos (5 minutos) es típicamente un buen número para comenzar.

[source,yaml]

netbox_database_maintenance: postgres

Si la base de datos postgres está configurada para permitir acceso solo a tablas específicas de la DB para el usuario configurado con NetBox, puedes establecer netbox_database_maintenance para reemplazar la base de datos predeterminada usada para verificar conexiones a otra tabla diferente a la postgres por defecto. Esta es una tabla vacía en cada base de datos postgres por defecto, pero algunas configuraciones pueden bloquear el acceso a esta tabla, por lo que se puede usar aquí una tabla diferente (es decir, netbox_prod).

[source,yaml]

Ejemplo de uso, el predeterminado es diccionario vacío

netbox_database_options:
sslmode: require
isolation_level: 3

Si necesitas establecer cualquier otra palabra clave de parámetro de PostgreSQL, puedes hacerlo aquí. Para casos como https://docs.djangoproject.com/en/3.1/ref/databases/#isolation-level[niveles de aislamiento] el valor numérico debe ser usado en lugar de la constante:
psycopg2.extensions.ISOLATION_LEVEL_SERIALIZABLE vs 3.
Solo agrega cosas aquí si realmente sabes lo que estás haciendo.

[source,yaml]

netbox_redis_host: 127.0.0.1
netbox_redis_port: 6379
netbox_redis_password: ''
netbox_redis_database: 0
netbox_redis_default_timeout: 300
netbox_redis_ssl_enabled: false
netbox_redis_insecure_skip_tls_verify: false

netbox_redis_cache_host: "{{ netbox_redis_host }}"
netbox_redis_cache_port: "{{ netbox_redis_port }}"
netbox_redis_cache_database: 1
netbox_redis_cache_password: "{{ netbox_redis_password }}"
netbox_redis_cache_default_timeout: "{{ netbox_redis_default_timeout }}"
netbox_redis_cache_ssl_enabled: "{{ netbox_redis_ssl_enabled }}"
netbox_redis_cache_insecure_skip_tls_verify: "{{ netbox_redis_insecure_skip_tls_verify }}"

Esto llena el diccionario de configuración REDIS en configuration.py. Usa el segundo conjunto de variables si deseas separar tu base de datos de caché de tu base de datos de webhooks.

[source,yaml]

netbox_redis_sentinels:

  • { host: '192.168.0.1', port: '5000' },
  • { host: '192.168.0.2', port: '5000' }
    netbox_redis_sentinel_service: 'netbox'
    netbox_redis_password: ''
    netbox_redis_database: 0
    netbox_redis_default_timeout: 300
    netbox_redis_ssl_enabled: false

netbox_redis_cache_sentinels: "{{ netbox_redis_sentinels }}"
netbox_redis_cache_sentinel_service: "{{ netbox_redis_sentinel_service }}"
netbox_redis_cache_database: 1
netbox_redis_cache_password: "{{ netbox_redis_password }}"
netbox_redis_cache_default_timeout: "{{ netbox_redis_default_timeout }}"
netbox_redis_cache_ssl_enabled: "{{ netbox_redis_ssl_enabled }}"

Usa esta sintaxis si tu redis está instalado con arquitectura de sentinel (múltiples nodos). Usa el segundo conjunto de variables si deseas separar tu base de datos de caché de tu base de datos de webhooks.

[source,yaml]

netbox_rqworker_processes: 1

Especifica cuántos trabajadores de la cola de solicitudes deberían ser iniciados por el servicio systemd. Puedes dejar esto en el valor predeterminado de 1, a menos que tengas un gran número de informes, scripts y otras tareas en segundo plano.

[source,yaml]

netbox_config:
#SECRET_KEY:
ALLOWED_HOSTS:
- localhost
- 127.0.0.1
#NAPALM_USERNAME:
#NAPALM_PASSWORD:
MEDIA_ROOT: "{{ netbox_shared_path }}/media"
REPORTS_ROOT: "{{ netbox_shared_path }}/reports"
SCRIPTS_ROOT: "{{ netbox_shared_path }}/scripts"

Este es un diccionario de configuraciones usadas para templar configuration.py de NetBox. Consulta http://netbox.readthedocs.io/en/stable/configuration/mandatory-settings/[Configuraciones Obligatorias] y http://netbox.readthedocs.io/en/stable/configuration/optional-settings/[Configuraciones Opcionales] de la documentación de NetBox para más detalles, así como examples/netbox_config.yml en este repositorio.

No es necesario definir SECRET_KEY aquí - este rol automáticamente creará uno para ti en {{ netbox_shared_path }}/generated_secret_key. La SECRET_KEY será leída de este archivo en ejecuciones subsecuentes, a menos que configures esto más adelante en tu playbook. Ten en cuenta que deberías definir la SECRET_KEY si estás desplegando múltiples instancias de NetBox detrás de un balanceador de carga.

Si has habilitado la integración de NAPALM en este rol, también necesitarás configurar las credenciales de NAPALM aquí.

MEDIA_ROOT/REPORTS_ROOT/SCRIPTS_ROOT, aunque no son obligatorias en la documentación de NetBox, son obligatorias en este rol para evitar perder estos archivos durante las actualizaciones (este rol no actualiza NetBox en su lugar). Debería establecerse en un directorio que sea permanente y que no se pierda durante la actualización (el predeterminado, que se mencionó anteriormente, se puede usar sin problema). Este rol intentará crear estos directorios y cambiar su propiedad a lo que esté establecido en netbox_user.

[source,yaml]

netbox_scripts: []
netbox_reports: []

https://netbox.readthedocs.io/en/stable/additional-features/custom-scripts/[Scripts] y https://netbox.readthedocs.io/en/stable/additional-features/reports/[Informes] para cargar para su uso dentro de NetBox. Estos deberían ser listas de diccionarios con un atributo src, especificando la ruta local al script o informe, y un atributo name, especificando el nombre del módulo (nombre del script/informe). Por ejemplo:

[source,yaml]

Ejemplo

netbox_scripts:

  • src: netbox_scripts/migrate_application.py
    name: migrate_application
    netbox_reports:
  • src: netbox_reports/devices.py
    name: devices

Esto copiará netbox_scripts/migrate_application.py desde tu directorio de playbook a {{ netbox_config.SCRIPTS_ROOT }}/migrate_application.py y netbox_reports/devices.py a {{ netbox.config.REPORTS_ROOT }}/devices.py.

[source,yaml]

netbox_pip_packages: []

Ejemplo:

netbox_pip_packages:

Esta es una lista de paquetes adicionales para instalar a través de pip dentro del entorno virtual de NetBox. Puedes especificar cualquier artefacto válido que pip entienda.

Si listás algún plugin aquí, asegúrate de incluir las configuraciones de plugin apropiadas dentro de la variable de rol netbox_config. Lee https://netbox.readthedocs.io/en/stable/plugins/[Plugins] para más información.

[source,yaml]

netbox_user: netbox
netbox_group: netbox
netbox_home: /srv/netbox
netbox_releases_path: "{{ netbox_home }}/releases"
netbox_git_repo_path: "{{ netbox_releases_path }}/git-repo"
netbox_git_deploy_path: "{{ netbox_releases_path }}/git-deploy"
netbox_stable_path: "{{ netbox_releases_path }}/netbox-{{ netbox_stable_version }}"
netbox_current_path: "{{ netbox_home }}/current"
netbox_shared_path: "{{ netbox_home }}/shared"

Estos son todos los detalles de despliegue que puedes modificar para cambiar el usuario de la aplicación y las ubicaciones de almacenamiento de la aplicación. netbox_releases_path almacena todos los lanzamientos de NetBox que has desplegado. netbox_git_repo_path es donde el repositorio Git se clonará y debe permanecer intacto, mientras que netbox_git_deploy_path es donde se extraerá un git archive utilizando la referencia netbox_git_version. netbox_stable_path es la carpeta extraída de un archivo tar de versión. netbox_current_path se enlazará simbólicamente al lanzamiento seleccionado y se usará en archivos de servicio/configuración como la ubicación donde está instalado NetBox. netbox_shared_path está destinado a almacenar archivos de configuración y otro contenido "compartido", como registros.

[source,yaml]

netbox_socket: "127.0.0.1:8000"
netbox_protocol: http
netbox_processes: "{{ ansible_processor_vcpus }}"

netbox_socket define a qué se unirá el servicio uWSGI y puede establecerse en cualquier dirección válida https://www.freedesktop.org/software/systemd/man/systemd.socket.html#ListenStream=[ListenStream] (socket de systemd). Establece netbox_protocol en uwsgi si deseas que uWSGI hable WSGI (por ejemplo, si estás ejecutando nginx como un balanceador de carga). netbox_processes define cuántos trabajadores de NetBox levantará uWSGI para atender solicitudes.

[source,yaml]

netbox_application_log: "file:{{ netbox_shared_path }}/application.log"
netbox_requests_log: "file:{{ netbox_shared_path }}/requests.log"

Estos definen dónde se almacenarán los registros. Puedes usar instalaciones de registro externas en lugar de archivos locales si lo deseas, http://uwsgi-docs.readthedocs.io/en/latest/Logging.html#pluggable-loggers[a medida que uWSGI lo soporte]. El registro de la aplicación corresponde a logger y el registro de solicitudes a req-logger.

[source,yaml]

netbox_ldap_enabled: false
netbox_ldap_config_template: netbox_ldap_config.py.j2

Activa netbox_ldap_enabled a true para configurar la autenticación LDAP para NetBox. netbox_ldap_config_template debería ser la ruta a tu plantilla; por defecto, Ansible buscará en el directorio templates/ de tu playbook. Puedes encontrar un ejemplo en examples/. También necesitarás establecer netbox_config.REMOTE_AUTH_BACKEND en netbox.authentication.LDAPBackend.

CONSEJO: Por defecto, un superusuario local (no LDAP) todavía será creado por este rol. Si esto no es deseable, considera activar netbox_superuser_enabled.

[source,yaml]

netbox_napalm_enabled: false
netbox_napalm_packages:

  • napalm

Activa netbox_napalm_enabled para habilitar la integración de NAPALM en NetBox. Debes definir NAPALM_USERNAME y NAPALM_PASSWORD en la variable netbox_config para poder usar NAPALM. Agrega bibliotecas adicionales de Python de NAPALM listándolas en netbox_napalm_packages (p. ej., napalm-eos).

[source,yaml]
netbox_metrics_enabled: false

Activa netbox_metrics_enabled a true para habilitar métricas de aplicación (a través de https://github.com/korfuri/django-prometheus[django-prometheus]). Esto añade piezas relevantes de configuración para un manejo adecuado de métricas. (https://netbox.readthedocs.io/en/stable/additional-features/prometheus-metrics/[más información]).

[source,yaml]

netbox_metrics_dir: netbox_metrics
netbox_metrics_path: "/run/{{ netbox_metrics_dir }}"

El nombre del directorio donde se almacenan los archivos de métricas se puede establecer con netbox_metrics_dir. Sin embargo, netbox_metrics_path debe permanecer en el valor predeterminado (como se ve arriba) para trabajar con systemd y el parámetro RuntimeDirectory (que solo apunta a /run).

[source,yaml]
netbox_keep_uwsgi_updated: false

Activa netbox_keep_uwsgi_updated a true si deseas asegurarte de que tu servidor uwsgi esté en la última versión; de lo contrario, uwsgi no se actualizará en ejecuciones posteriores de tu playbook.

[source,yaml]
netbox_uwsgi_options: {}

Especifica opciones de configuración adicionales para insertar en uwsgi.ini aquí. Se espera que sea un diccionario de pares clave/valor, p. ej., buffer-size: 65535.

[source,yaml]
netbox_uwsgi_in_venv: false

Activa netbox_uwsgi_in_venv a true si quieres que uwsgi se instale en el mismo entorno virtual que NetBox. De lo contrario, se instalará a nivel del sistema en la ruta de biblioteca de la versión de Python utilizada para crear el entorno virtual (comportamiento normal/legado).

ADVERTENCIA: Existe la posibilidad de que esto se convierta en el valor predeterminado en una versión posterior de este rol (creo que después de más pruebas interplataforma). Consulta https://github.com/lae/ansible-role-netbox/issues/144[issues #144] para más detalles.

[source,yaml]
netbox_install_epel: true

Activa netbox_install_epel a false si no deseas que este rol instale el Fedora EPEL por ti. Esto puede ser útil para entornos empresariales donde los repositorios del sistema son gestionados/mirrored por la empresa.

[source,yaml]

netbox_packages: []
netbox_python_packages: []
netbox_python_binary: /usr/bin/python{{ some version }}
netbox_ldap_packages: []

Estas variables se generan dinámicamente en función de la distribución de destino. Puedes consultar los valores por defecto debajo del directorio vars/. Puedes usar estas variables para apuntar a un sistema operativo no compatible (aunque siéntete libre de abrir una PR para agregar soporte) o para especificar un intérprete de Python personalizado (como PyPy) que se utilizará para el despliegue. Sin embargo, ten en cuenta que el soporte por este rol puede ser limitado para otras instalaciones de Python.

== Ejemplo de Playbook

El siguiente instala PostgreSQL y crea un usuario con el robusto rol de Postgres de @geerlingguy, luego procede a desplegar y configurar NetBox utilizando un socket unix local para hablar con el servidor Postgres con el usuario de base de datos netbox por defecto.

[source,yaml,subs="attributes"]

  • hosts: netbox.idolactiviti.es
    become: yes
    roles:
    • geerlingguy.postgresql
    • davidwittman.redis
    • {role}
      vars:
      netbox_stable: true
      netbox_database_socket: "{{ postgresql_unix_socket_directories[0] }}"
      netbox_superuser_password: netbox
      netbox_socket: "0.0.0.0:80"
      netbox_config:
      ALLOWED_HOSTS:
      • netbox.idolactiviti.es
        MEDIA_ROOT: "{{ netbox_shared_path }}/media"
        REPORTS_ROOT: "{{ netbox_shared_path }}/reports"
        SCRIPTS_ROOT: "{{ netbox_shared_path }}/scripts"
        postgresql_users:
      • name: "{{ netbox_database_user }}"
        role_attr_flags: CREATEDB,NOSUPERUSER
        redis_bind: 127.0.0.1
        redis_version: 6.0.9
        redis_checksum: sha256:dc2bdcf81c620e9f09cfd12e85d3bc631c897b2db7a55218fd8a65eaa37f86dd

Nota el atributo CREATEDB.

Asumiendo que ya tienes un servidor PG en funcionamiento con el usuario netbox_prod_user creado, posee una base de datos llamada netbox_prod, y permite que el host en el que estás instalando NetBox se autentique con ella a través de TCP:

[source,yaml,subs="attributes"]

  • hosts: netbox.idolactiviti.es
    become: yes
    roles:
    • davidwittman.redis
    • {role}
      vars:
      netbox_stable: true
      netbox_superuser_password: netbox
      netbox_socket: "0.0.0.0:80"
      netbox_config:
      ALLOWED_HOSTS:
      • "{{ inventory_hostname }}"
        MEDIA_ROOT: "{{ netbox_shared_path }}/media"
        REPORTS_ROOT: "{{ netbox_shared_path }}/reports"
        SCRIPTS_ROOT: "{{ netbox_shared_path }}/scripts"
        netbox_database_host: pg-netbox.idolactiviti.es
        netbox_database_port: 15432
        netbox_database: netbox_prod
        netbox_database_user: netbox_prod_user
        netbox_database_password: "very_secure_password_for_prod"
        netbox_database_maintenance: netbox_prod
        redis_bind: 127.0.0.1
        redis_version: 6.0.9
        redis_checksum: sha256:dc2bdcf81c620e9f09cfd12e85d3bc631c897b2db7a55218fd8a65eaa37f86dd

Consulta el directorio examples/ para más.

== Solución de problemas

=== uWSGI reseteando conexiones TCP
Cuando netbox_protocol está establecido en http, uWSGI podría mostrar un comportamiento extraño y resetear conexiones TCP aparentemente al azar. Esto puede manifestarse en un error de "conexión restablecida por el par", por ejemplo, cuando trabajas con la API usando https://github.com/netbox-community/pynetbox[pynetbox]. Si te afecta esto, intenta cambiar netbox_protocol a uwsgi y usar un balanceador de carga, o ajustando tus netbox_uwsgi_options de la siguiente manera. Consulta https://github.com/lae/ansible-role-netbox/issues/130#issuecomment-847571006[este problema de GitHub] para una discusión relacionada.
[source,yaml,subs="attributes"]

netbox_uwsgi_options:
http-keepalive: "true"
http-auto-chunked: "true"
add-header: "Connection: Close"

Acerca del proyecto

Installs and configures NetBox, a DCIM suite, in a production setting.

role datacenter dcim ipam networking web
Instalar
ansible-galaxy install lae.netbox
GitHub repositorio
207 estrellas
72 bifurcaciones
15 problemas abiertos
Licencia
mit
Descargas
107.6k
Propietario