Skip to main content
Version: v5.0 Stable

Connect to NetBox

NetBox records data center devices and network information. vCluster Platform uses a NetBox connector to synchronize bare metal machine inventory.

Prerequisites​

  • Platform admin access to the management API.
  • The auto-nodes-metal3 license feature.
  • A NetBox HTTP or HTTPS endpoint reachable from Platform.
  • A NetBox API token with access to the inventory selected by your node provider.
Grants bound NetBox references

A node provider can reference only a NetBox connector its owner can use. If the grant is revoked, Platform stops syncing that node provider from NetBox but keeps the machines it already imported. See Reference it from a node provider.

Create the token in the NetBox UI and grant read access to the selected devices, interfaces, IP addresses, MAC addresses, modules, module types, and tags. Scope access to the inventory selected by your node provider. Follow the NetBox documentation for token permissions and installation.

Create the connector​

Save this manifest as netbox-connector.yaml. Replace the URL and token with your NetBox settings:

Modify the following with your specific values to generate a copyable command:
apiVersion: management.loft.sh/v1
kind: Connector
metadata:
name: netbox-main
spec:
displayName: Primary NetBox
# This payload section selects the netbox type.
netBox:
url: https://netbox.example.com
apiToken: "replace-with-netbox-token"
insecure: false

Create it against the Platform management API:

Modify the following with your specific values to generate a copyable command:
kubectl create -f netbox-connector.yaml
kubectl get connectors.management.loft.sh netbox-main -o yaml

url must be an HTTP or HTTPS URL. apiToken is required when no stored token exists. insecure defaults to false.

Configured=True validates the payload, without testing NetBox connectivity or the token's inventory permissions. Check the node provider and inventory synchronization if machines don't appear.

Reference it from a node provider​

In the existing Metal3 NodeProvider, set the NetBox Secret reference to the connector name and the Platform namespace:

Modify the following with your specific values to generate a copyable command:
spec:
metal3:
netBox:
secretRef:
name: netbox-main
namespace: vcluster-platform

The Connector is cluster-scoped, but its backing Secret lives in the Platform namespace. This consumer still uses secretRef. Keep the reference in that namespace.

Platform refuses a node provider whose secretRef doesn't name a NetBox connector in the Platform namespace that the node provider's owner can use. Missing, ungranted, wrong-type, and out-of-namespace references all receive the same validation error on spec.metal3.netBox.secretRef, does not name a usable connector. Only creation and changes to the reference are checked. A node provider without an owner is checked as the platform, so it can't use a connector that's exclusive to a tenant. Grant the connector to the owning tenant first.

After the node provider reconciles, the machines that NetBox records appear in the platform's machine inventory. If they don't, see Troubleshoot synchronization.

Manage existing Secrets and credentials​

A Secret labeled loft.sh/connector-type: netbox in the Platform namespace appears through the API. Its url, apiToken, and insecure data keys map to spec.netBox.

Viewers and tenant sessions see the URL and insecure flag, but no API token. A connector admin can read the token. An empty token on update keeps the stored value.

For credential rotation, use a merge patch with the new token. Don't remove the connector while a node provider still references it.

Troubleshoot synchronization​

  • If creation returns a validation error, check the URL scheme and API token field.
  • If a node provider is refused with does not name a usable connector, check that secretRef names a NetBox connector in the Platform namespace and that the owning tenant has a grant for it.
  • If a node provider reports ConnectorUsable=False, its grant was lost (reason ConnectorUnusable) or its owner Tenant no longer exists (reason OwnerUnresolved). Restore the grant, or delete or reassign the node provider. Imported machines stay in the inventory until then.
  • If creation returns Forbidden, check management permissions and the Metal3 license feature.
  • If configuration passes but synchronization fails, check Platform-to-NetBox connectivity, TLS trust, token permissions, and the node provider's inventory selection.
  • If an API read omits the token, confirm whether your session has update permission. A tenant session always receives the reduced view.