Package netbox
provides an API 3.2 client for netbox-community's Netbox IPAM and DCIM service.
This package assumes you are using Netbox 3.2, as the Netbox 1.0 API no longer exists. If you need support for previous Netbox versions, you can still import the corresponding release of the library. For example, run go get github.com/netbox-community/go-netbox@netbox_v2.11
if you need compatibility with Netbox 2.11.
The github.com/netbox-community/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/netbox-community/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/netbox-community/go-netbox/netbox/client"
"github.com/netbox-community/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.16+
go get github.com/netbox-community/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.
The project comes with a containerized development environment that can be used from any platform. It is only required to have Git and Docker Desktop (or, separately, Docker and Docker Compose) installed on the machine.
To start the development environment, run the following command.
make
Then, to attach a shell in the container, run the command below.
make shell
Finally, to stop the development environment, run the following command.
make down
The library is almost entirely generated from the Netbox OpenAPI specification. Therefore, files under directories netbox/client
and netbox/models
should not be directly modified, as they will be overwritten in the next regeneration (see next section).
To fix issues in generated code, there are two options:
- Change the OpenAPI spec with pre-generation hooks (see
scripts/pre-generation
). - If the above is not possible, change the generated code with post-generation hooks (see
scripts/post-generation
).
To update the OpenAPI specification to the latest Netbox version and regenerate the library, run the following command.
make build
If regeneration of the library is needed for a specific Netbox version other than the latest one, pass the corresponding argument.
make build NETBOX_VERSION=3.0.0
In order to obtain the OpenAPI specification, the version of netbox-docker corresponding to the given Netbox version is used. However, it is also possible to provide a specific version of netbox-docker.
make build NETBOX_VERSION=3.0.0 NETBOX_DOCKER_VERSION=1.3.1