Package netbox provides an API 2.0 client for netbox-community's NetBox
IPAM and DCIM service.
This package assumes you are using NetBox 2.0, as the NetBox 1.0 API no longer exists.
This fork exists solely to support e-breuninger/terraform-provider-netbox. As such, some changes in this fork do only make sense in that context.
For a long time, the approach of taking the original netbox-provided swaggerfile, processing it and then generating a client from the processed swagger file was the only acceptable way for me to manage changes in this client. The main advantage of this was that changes in the netbox api in newer versions could mostly be implemented fast, while simultaneously ensuring that the fixes that are necessary to make the terraform provider work were always present in the code.
With NetBox 3.5, the NetBox authors decided to change the api documentation from openapi2 to openapi3. This means that the code generator that is being used in this project can no longer be used.
Switching the code generator will also induce the need to change every single api call in the terraform provider. Furthermore, I am no expert whatsoever on openapi (or even Go), so evaluating the different available openapi generators and then choosing one to use is not an endeavour I can pursue right now. This means we cannot re-generate the client with newer api specs right now or in the immediate future.
In conclusion, at the time of writing this, NetBox 3.5 is out quite some time already with NetBox 3.6 around the corner, so I decided that the show must go on and manual adjustments to this client are now the fastest way to allow the terraform provider to support newer NetBox versions. Changes to the swagger file or preprocessor still are the preferred way to implement things, however.
This will be re-evaluated if the list of to-dos in the netbox provider gets smaller (e.g. all newish versions are supported, custom fields are solved globally).
Links:
Original announcement of openapi3 change
Issue and discussion in https://github.com/netbox-community/go-netbox
tbd. Meanwhile, look at branches and tags.
NOTE: The list of changes is becoming too inconvenient to list here. See preprocess.py for all changes. The list below is incomplete at best or flat-out wrong!
Change models.ip_address.AssignedObject type to prevent json marshalling errors since this change
Add x-omitempty: false to some attributes, allowing them to be set to their empty value. issue
Change ConfigContext type for VMs and Devices #2
Fix LocalConfigContext to support arbitrary JSON object #4
Changes to allow available_ips to be created. (2b418d0d6d13d1edd0320d9424096f8f7d2cbbec)
- model returned by paths /*/available-ips/ from AvailableIP to IPAddress
- model IPAddress's assigned_object property from string to object otherwise it fails to unmarshal
The github.com/fbreckle/go-netbox/netbox package has some convenience functions for creating clients with the most common
configurations you are likely to 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/fbreckle/go-netbox/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/fbreckle/go-netbox/netbox/client"
"github.com/fbreckle/go-netbox/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)
}
Go 1.13+
go get github.com/fbreckle/go-netbox
The client is generated using go-swagger. This means the generated client makes use of github.com/go-openapi/runtime/client. If you need a more complex configuration, it is probably possible with a combination of this generated client and the runtime options.
The godocs for the go-openapi/runtime/client module explain
the client options in detail, including different authentication and debugging options. One thing I want to flag because
it is so useful: setting the DEBUG environment variable will dump all requests to standard out.
To regenerate the client with a new or different swagger schema, first clean the existing client, then replace swagger.json, run the json preprocessor (requires python3) and finally re-generate:
make clean
make preprocess
make generate