go-netbox

Go library to interact with NetBox IPAM and DCIM service.

Compatibility with Netbox

The version for Netbox and go-netbox will the same except for the last digit.

Example:

go-netbox v1.10.x is working with Netbox v1.10
go-netbox v1.11.x is working with Netbox v1.11

Using the client

The github.com/smutel/go-netbox/v3/netbox package has some convenience functions for creating clients with the most common configurations you likely need while connecting to NetBox. NewNetboxAt allows you to specify a hostname (including port, if you need it), and NewNetboxWithAPIKey allows you to specify both a hostname:port and API token.

import (
    "github.com/smutel/go-netbox/v3/netbox"
)
...
    c := netbox.NewNetboxAt("your.netbox.host:8000")
    // OR
    c := netbox.NewNetboxWithAPIKey("your.netbox.host:8000", "your_netbox_token")

If you specify the API key, you do not need to pass an additional authInfo to operations that need authentication, and can pass nil:

    c.Dcim.DcimDeviceTypesCreate(createRequest, nil)

If you connect to netbox via HTTPS you have to create an HTTPS configured transport:

package main

import (
	"os"

	httptransport "github.com/go-openapi/runtime/client"
	"github.com/smutel/go-netbox/v3/netbox/client"
	"github.com/smutel/go-netbox/v3/netbox/client/dcim"

	log "github.com/sirupsen/logrus"
)

func main() {
	token := os.Getenv("NETBOX_TOKEN")
	if token == "" {
		log.Fatalf("Please provide netbox API token via env var NETBOX_TOKEN")
	}

	netboxHost := os.Getenv("NETBOX_HOST")
	if netboxHost == "" {
		log.Fatalf("Please provide netbox host via env var NETBOX_HOST")
	}

	transport := httptransport.New(netboxHost, client.DefaultBasePath, []string{"https"})
	transport.DefaultAuthentication = httptransport.APIKeyAuth("Authorization", "header", "Token "+token)

	c := client.New(transport, nil)

	req := dcim.NewDcimSitesListParams()
	res, err := c.Dcim.DcimSitesList(req, nil)
	if err != nil {
		log.Fatalf("Cannot get sites list: %v", err)
	}
	log.Infof("res: %v", res)
}

How to contribute to this project

To contribute to this project, please follow the conventional commits rules.
Most of the code of this project will be generated using the swagger spec of Netbox and the go-swagger program.
You can change the behavior of the generated library by pushing patchs in the patchs folder.
The best is to see if the bug is due to a wrong swagger definition and to report this bug to the Netbox project.
If the bug is due to the go-swagger program the best is to create a bug here go-swagger.

How to test your work locally

Requirements

docker
docker-compose
swagger installed somewhere (/usr/local/bin)
netbox-docker project installed somewhere

Installing the go-netbox

$ # Install jsonlint
$ apt-get install python3-demjson
$ mkdir -p ~/go/src/github.com/smutel
$ cd ~/go/src/github.com/smutel
$ git clone git@github.com:smutel/go-netbox.git
$ export GITHUB_WORKSPACE=~/go/src

Regenerating the library

$ cd ~/go/src/github.com/smutel/go-netbox/utils
$ ./netbox_generate_client