Skip to content

Latest commit

 

History

History
247 lines (206 loc) · 19.9 KB

README.md

File metadata and controls

247 lines (206 loc) · 19.9 KB
Raw

Netbox-SSOT

Go GitHub last commit GitHub Tag codecov GitHub License

Netbox-ssot is a small but powerful microservice designed to keep your Netbox instance in sync with external data sources.

It is designed to be run as a cronjob, and will periodically update Netbox with the latest data from the external sources. It syncs each source in parallel to speed up the process of syncing.

Currently, the supported external data sources types are:

Warning

This project is still under heavy development, use with caution.

  • v1.x.x works with netbox>=4.0.0

  • v0.x.x works with netbox>=3.7.0

Configuration

Netbox-ssot is configured via a single yaml file. The configuration file is divided into three sections:

  • logger: Logger configuration
  • netbox: Netbox configuration
  • source: Array of configuration for each data source

Example configuration can be found here.

Logger

Parameter Description Type Possible values Default Required
logger.level Log level int 0-3 1 Yes
logger.dest Log output filename. Default "" representing stdout. str Any valid path "" No

Netbox

Parameter Description Type Possible values Default Required
netbox.apiToken Netbox API token. str Any valid token "" Yes
netbox.hostname Hostname of your netbox instance (e.g netbox.example.com). str Valid hostname "" Yes
netbox.port Port of your netbox instance. int 0-65536 443 No
netbox.httpScheme HTTP scheme of your netbox instance. str [http, https] https No
netbox.validateCert Validate the TLS certificate of your netbox instance. bool [true, false] false No
netbox.timeout Max timeout for api call of your netbox instance. int >=0 30 No
netbox.removeOrphans If set to true all objects, marked with netbox-ssot tag that were not found during this iteration are automatically deleted. If set to false, objects that were not found are marked with an Orphan tag. We can then use netbox.removeOrphansAfterDays to remove the orphans after n days that they were not seen on the sources. bool [true, false] true No
netbox.removeOrphansAfterDays Specifies the number of days to wait before automatically deleting objects marked as Orphan. This setting is only applicable if netbox.removeOrphans is set to false. A value of 5 means objects are deleted in five days after being marked as Orphan and not found since. int >0 MaxInt No
netbox.tag Tag to be applied to all objects managed by netbox-ssot. string any "netbox-ssot" No
netbox.tagColor TagColor for the netbox-ssot tag. string any "07426b" No
netbox.sourcePriority Array of source names in order of priority. If an object (e.g. Vlan) is found in multiple sources, the first source in the list will be used. []string any [] No
netbox.caFile Path to a self signed certificate for netbox. string Valid path "" No

Source

Parameter Description Source Type Type Possible values Default Required
source.name Name of the data source. all str any "" Yes
source.type Type of the data source. all str [ovirt, vmware, dnac, proxmox, paloalto] "" Yes
source.httpScheme Http scheme for the source all str [ http,https] https No
source.hostname Hostname of the data source. all str any "" Yes
source.port Port of the data source. all int 0-65536 443 No
source.username Username of the data source account. all str any "" Yes
source.password Password of the data source account. all str any "" Yes
source.apiToken API token of the data source account. [fortigate] str any "" Yes
source.validateCert Enforce TLS certificate validation. all bool [true, false] false No
source.tagColor TagColor for the source tag. all string any Predefined No
source.ignoredSubnets List of subnets, which will be ignored (e.g. IPs won't be synced). all []string any [] No
source.interfaceFilter Regex representation of interface names to be ignored (e.g. (cali|vxlan|flannel|[a-f0-9]{15})) all string any [] No
source.collectArpData Collect data from the arp table of the device. [paloalto, ios-xe] bool [true, false] false No
source.datacenterClusterGroupRelations Regex relations in format regex = clusterGroupName, that map each datacenter that satisfies regex to clusterGroupname (see #130). [vmware, ovirt] []string any [] No
source.hostSiteRelations Regex relations in format regex = siteName, that map each host that satisfies regex to site. all []string any [] No
source.clusterSiteRelations Regex relations in format regex = siteName, that map each cluster that satisfies regex to site. all []string any [] No
source.clusterTenantRelations Regex relations in format regex = tenantName, that map each cluster that satisfies regex to tenant. all []string any [] No
source.hostTenantRelations Regex relations in format regex = tenantName, that map each host that satisfies regex to tenant. all []string any [] No
source.vmTenantRelations Regex relations in format regex = tenantName, that map each vm that satisfies regex to tenant. all []string any [] No
source.vlanGroupRelations Regex relations in format regex = vlanGroup, that map each vlan that satisfies regex to vlanGroup. all []string any [] No
source.vlanTenantRelations Regex relations in format regex = tenantName, that map each vlan that satisfies regex to tenant. all []string any [] No
source.wlanTenantRelations Regex relations in format regex = tenantName, that map each wlan that satisfies regex to tenant. [dnac] []string any [] No
source.customFieldMappings Mappings of format customFieldName = option. Currently, supported options are contact, owner, description. [vmware] []string any [] No
source.caFile Path to a self signed certificate for the source. any string Valid path "" No

Example config

logger:
  level: 1
  dest: ""

netbox:
  apiToken: "el1aof2azu6n50ks5zcenp3..."
  hostname: "netbox.example.com"
  httpScheme: http
  port: 443
  timeout: 30
  sourcePriority: ["olvm", "prodvmware", "prodprox", "dnacenter", "testvmware", "pa-uk", "fmc-lab"] # Not required, but recommended

source:
  - name: olvm
    type: ovirt
    hostname: ovirt.example.com
    port: 443
    username: "admin"
    password: "topsecret"
    interfaceFilter: (cali|vxlan|flannel|docker|[a-f0-9]{15})

  - name: prodvmware
    type: vmware
    hostname: vcenter.example.com
    username: user
    password: "top_secret"
    clusterSiteRelations:
      - .* = ExampleSite
    hostSiteRelations:
      - .*_NYC = New York
      - nyc.* = New York
    customFieldMappings: # Here we define map of our custom field names, to 3 option [email, owner, description]
      - Mail = email
      - Creator = owner
      - Description = description

  - name: prodprox
    type: proxmox
    username: svc@pve
    password: changeme
    hostname: 192.168.1.254
    port: 8006
    validateCert: false
    clusterSiteRelations:
     - .* = Site

  - name: forti
    type: fortigate
    hostname: forti.example.com
    apiToken: "apitokenhere"
    validateCert: False
    hostTenantRelations:
      - .* = MyTenant
    hostSiteRelations:
      - .* = MyTenant
    vlanTenantRelations:
      - .* = MyTenant

  - name: pa-uk
    type: paloalto
    hostname: 192.168.1.52
    username: user
    password: passw0rd
    hostTenantRelations:
      - .* = MyTenant
    hostSiteRelations:
      - .* = MySite
    vlanTenantRelations:
      - .* = MyTenant
    collectArpData: true

  - name: dnacenter
    type: dnac
    hostname: dnac.example.com
    username: user
    password: "pa$$w0rd"
    vlanTenantRelations:
      - .* = MyTenant

  - name: fmc-lab
    type: fmc
    hostname: 172.16.1.30
    username: user
    password: password
    validateCert: False
    hostTenantRelations:
      - .* = MyTenant
    hostSiteRelations:
      - .* = MySite
    vlanTenantRelations:
      - .* = MyTenant

  - name: cs1
    type: ios-xe
    hostname: 10.10.1.1
    username: user
    password: password
    port: 830
    validateCert: False
    hostTenantRelations:
      - .* = MyTenant
    hostSiteRelations:
      - .* = MySite
    vlanTenantRelations:
      - .* = MyTenant
    collectArpData:
      true

Deployment

Via docker

docker run -v /path/to/config.yaml:/app/config.yaml ghcr.io/bl4ko/netbox-ssot

Via k8s

Create k8s secret from self defined config.yaml:

kubectl create secret generic netbox-ssot-secret --from-file=config.yaml

Apply cronjob with custom settings:

kubectl apply -f cronjob.yaml

Using self signed certificate

Create self signed certificate e.g.:

kubectl create secret generic netbox-ssot-cert --from-file=sub.pem=./sub.pem

Use cronjob with cert mounted:

kubectl apply -f cronjob_with_cert.yaml