Skip to content

Latest commit

 

History

History
152 lines (113 loc) · 4.87 KB

README.md

File metadata and controls

152 lines (113 loc) · 4.87 KB
Raw

cachet netbox sync

An application to import netbox data (circuits, virtual machines, sites, IP adresses, tenants, clusters, ...) into cachet. It saves you from manually updating your status page inventory when you add a new component to report status on. All entries can be filtered and grouped arbitrarily as configurated in a simple plain-text file - no code necessary.

[source.netbox.u6]
endpoint=virtualization.virtual_machines
filters.tenant=uberspace-6
filters.status=1
group_by_field=tenant.name

This example will fetch all active VMs beloning to Uberspace 6, put them into a group called "Uberspace 6" and display their status on your cachet instance.

Setup

The tool can be installed conventionally using the python package manager or newage new age-y using docker.

Python pip

The easiest way to install this tool is using pip, the python package manager. This will install the dependencies as well as the cachet_netbox_sync command into the python context of the currently logged in user.

$ pip install git+https://github.com/uberspace/cachet_netbox_sync.git

Docker

Alternatively, you can use the uberspace/cachet_netbox_sync docker image to keep the python dependency management off your system.

Command

The docker image can be used like a shell command like so:

$ docker pull uberspace/cachet_netbox_sync
$ docker run -V config.ini:/config.ini uberspace/cachet_netbox_sync --config /config.ini

Custom image

Instead of using our pre-built image, you can make your own. Save the following snippet as a Dockerfile, place a config.ini next to it and there you go: your very own cachet_netbox_sync with baked-in config. Just be carefull to not include any secrets in there, as they can be read by anyone in possession of the image.

FROM uberspace/cachet_netbox_sync
COPY config.ini /config.ini
ENTRYPOINT ["cachet_netbox_sync", "-c", "/config.ini"]

Gitlab

If you have a GitLab with GitLab-CI running, you can use it to refresh your cachet on-demand or in a cronjob-like fashion.

  1. create a new project
  2. commit a config.ini
  3. add your secrets as variables
  4. commit the following .gitlab-ci.yml
---
sync_cachet:
  image:
    name: uberspace/cachet_netbox_sync
    # https://gitlab.com/gitlab-org/gitlab-runner/issues/1170#note_271904909
    entrypoint: [""]
  script:
    - cachet_netbox_sync --config cachet_netbox_sync.ini

Operation

  1. get a cachet API token from https://cachet.example.com/dashboard/user
  2. get a netbox readonly API token from https://netbox.example.com/admin/users/token/
  3. copy config.example.ini to anywhere (e.g. ~/.cachet_netbox_sync.config.ini) and edit it according to the comments in the file
  4. if you decide to leave the API tokens out of the config file, make sure CACHET_TOKEN and NETBOX_TOKEN are defined in the environment you will execute cachet_netbox_sync from.
  5. run cachet_netbox_sync -c config.ini. The configuration path must always be supplied as a parameter.

Syncing

The tool syncs two types of objects: components (e.g. VMs, network or sites) and component groups. In both cases data is taken from netbox to cachet, never the other way around.

Components

  • imports netbox data specified [source.netbox.*] sections into cachet
  • deletes all components, which are not present in netbox
  • deletes only if there are fewer or equal to component_delete_limit components to be deleted
  • only touches components which have the cachet-netbox-sync tag, so you can create additional components in the cachet web interface.

Component Groups

  • creates all groups implicitly specified via group_by_field in sources
  • deletes (or keeps) groups, which are not present in netbox, depending on the unknown_group_action setting
  • just like components, there is a group_delete_limit setting

Configuration

Please refer to the comments in config.example.ini for details on how to configure syncing.

Automation

Once there is a working configuration, a cronjob can be used to sync the data regularily. The script can also be executed by your CI/CD system or anything else you use internally.

Add the follwing to the crontab of the user you ran make install as:

0 * * * * cachet_netbox_sync -c ~/.cachet_netbox_sync.config.ini

This assumes your $PATH includes ~/.local/bin, which is where pip installs python "binaries".

Dev Setup

$ git clone https://github.com/uberspace/cachet_netbox_sync.git
$ cd cachet_netbox_sync
$ virtualenv venv
$ source venv/bin/activate
$ make devsetup

To actually run the tool you will need netbox and cachet instances as well as a configuration file.