NetBox#

Overview#

The NetBox app enables users to integrate/synchronize various resources between NetBox and EDA by providing the following resource types:

• Instance: Defines the target NetBox instance to interact with.
• Allocation: Specifies the type of EDA allocation to create based on the NetBox's Prefixes.

EDA continues to use its own allocation pools for IP addresses, indices and subnets, but the NetBox app will dynamically create the allocation pools based on the NetBox's IPAM > Prefixes objects and post the allocated objects back to NetBox.

This mode of operation allows the users to leverage NetBox's IPAM features and dynamically create the allocation pools in EDA. Check out the end-to-end example for more details.

Supported objects#

In the current version of the NetBox app EDA's allocation pools are created based on the NetBox Prefix objects. Depending on the Prefix's Status mode, the allocation pools of certain type can be created.

More objects will be supported in the future.

NetBox Configuration#

To enable NetBox to send updates to the EDA app

Create a Webhook#

The Webhook in NetBox is triggered by the NetBox's Event Rule and allows NetBox to send updates to the EDA app.

• Name: Any meaningful identifier

• URL: https://${EDA_ADDR}:${EDA_PORT}/core/httpproxy/v1/netbox/webhook/${INSTANCE_NAMESPACE}/${INSTANCE_NAME}
  Replace the ${INSTANCE_NAMESPACE} with the EDA namespace name you will use to create the NetBox Instance custom resource later. The ${INSTANCE_NAME} should be the name of the NetBox Instance custom resource you will create in the Instance Customer Resource section.

  For example, if you want to create EDA-NetBox integration for the EDA Allocation pools in the eda namespace, and you will name your NetBox Instance CR simply netbox, then the URL will be:

  https://youredaaddress.com:9443/core/httpproxy/v1/netbox/webhook/eda/netbox
  

• Method: POST

• Secret: Choose a signature secret (plaintext string) that will be used to validate the webhook request. The matching Kubernetes secret with the same string will be created later in the Kubernetes Secrets section.
• SSL verification: Based on your setup either leave SSL verification enabled or disable it.
• Leave all other settings as default.

Create an Event Rule#

An event rule is used to trigger webhook based on the events happening in NetBox. You will find the Event Rules menu item under the Integrations section in NetBox.

• Name: Choose a relevant name
• Objects: Include IPAM IPAddresses and IPAM Prefixes
• Enabled: Yes

• Event Types:

  • Object created
  • Object updated
  • Object deleted

• Action:

  • Type: Webhook
  • Webhook: Select the one created above

Generate an API Token#

Using the Admin → Authentication → API Tokens menu create a NetBox API token for the NetBox user that EDA app will use. Enable write permission for the API token.

Configure User Permissions#

In the Admin → Authentication → Permissions menu, grant the user you created the API token for the permissions to create, update, and delete for the following objects:

• IPAM > IPAddress
• IPAM > Prefix
• Extras > Tag (a.k.a Customizations.Tags in earlier versions)
• Extras > Custom Field (a.k.a Customizations.CustomFields in earlier versions)

Configure Global VRF Setting#

Starting with NetBox 4.2.6, the ENFORCE_GLOBAL_UNIQUE setting has been flipped to true, this may have negative effect on EDA installations that use multiple topologies using the same IP addressing.

As per the NetBox documentation, to relax this enforcement change the configuration setting of the global VRF via environment variable or in the configuration.py file.

ENFORCE_GLOBAL_UNIQUE=false

Tags#

In case you plan to have more than one "NetBox Prefix" → "EDA allocation pool" mapping, you will need to create a tag in NetBox for each distinct allocation pool and assign it to the Prefix object in NetBox.

In the EDA Allocation resource you then reference the tag name in the tags field and the allocation pool will be created based on the prefixes with that tag.

Kubernetes Secrets#

The NetBox API Token and the Webhook secret must be created as Kubernetes Secrets in the same namespace where the EDA NetBox app will run (example: eda). The data for these secrets must be provided as base64 encoded strings.

Secret for the webhook:

apiVersion: v1
kind: Secret
metadata:
  name: netbox-webhook-signature
  namespace: eda
type: Opaque
data:
  # base64-encoded signature key that NetBox will use
  signatureKey: ${NETBOX_WEBHOOK_SIGNATURE_KEY}

cat << EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: netbox-webhook-signature
  namespace: eda
type: Opaque
data:
  # base64-encoded signature key that NetBox will use
  signatureKey: ${NETBOX_WEBHOOK_SIGNATURE_KEY}
EOF

Secret for the API Token:

apiVersion: v1
kind: Secret
metadata:
  name: netbox-api-token
  namespace: eda
type: Opaque
data:
  # base64-encoded NetBox API token with IPAM permissions
  apiToken: ${NETBOX_API_TOKEN}

cat << EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: netbox-api-token
  namespace: eda
type: Opaque
data:
  # base64-encoded NetBox API token with IPAM permissions
  apiToken: ${NETBOX_API_TOKEN}
EOF

EDA Configuration#

Installation#

Install the NetBox app from the EDA Store or with kubectl:

apiVersion: core.eda.nokia.com/v1
kind: Workflow
metadata:
  name: netbox-install
  namespace: eda-system
spec:
  type: app-installer
  input:
    operation: install
    apps:
      - app: netbox
        catalog: eda-catalog-builtin-apps
        vendor: nokia
        version:
          type: semver
          value: v1.0.0

cat << 'EOF' | kubectl apply -f -
apiVersion: core.eda.nokia.com/v1
kind: Workflow
metadata:
  name: netbox-install
  namespace: eda-system
spec:
  type: app-installer
  input:
    operation: install
    apps:
      - app: netbox
        catalog: eda-catalog-builtin-apps
        vendor: nokia
        version:
          type: semver
          value: v1.0.0

EOF

Instance Resource#

Defines connection details to the NetBox instance from the EDA NetBox app:

apiVersion: netbox.eda.nokia.com/v1alpha1
kind: Instance
metadata:
  name: netbox1
  namespace: eda
spec:
  url: http://${NETBOX_ADDR}:${NETBOX_PORT}
  # Name of a secret containing the base64-encoded API token
  # under the `apiToken` key
  apiToken: netbox-api-token
  # Name of a secret containing the base64-encoded signature key
  # under the `signatureKey` key
  signatureKey: netbox-webhook-signature

cat << 'EOF' | kubectl apply -f -
apiVersion: netbox.eda.nokia.com/v1alpha1
kind: Instance
metadata:
  name: netbox1
  namespace: eda
spec:
  url: http://${NETBOX_ADDR}:${NETBOX_PORT}
  # Name of a secret containing the base64-encoded API token
  # under the `apiToken` key
  apiToken: netbox-api-token
  # Name of a secret containing the base64-encoded signature key
  # under the `signatureKey` key
  signatureKey: netbox-webhook-signature
EOF

The NetBox Instance resource requires a user to provide names of the two Kubernetes secrets created in the same namespace where the Instance is deployed:

1. The apiToken field references the secret containing the NetBox API Token.
2. The webhookSignatureSecret field references the secret containing the Webhook signature secret.

After creation, check the status of the Instance resource to verify successful connection.

Allocation Resource#

With Allocation resource a user specifies which NetBox Prefixes should create which EDA allocation pools.

apiVersion: netbox.eda.nokia.com/v1alpha1
kind: Allocation
metadata:
  name: netbox-isl-pool
  namespace: eda
spec:
  enabled: true
  instance: netbox  # <-- Reference to the Instance resource
  tags:
    - eda-isl-pool  # <-- Must match tags on NetBox prefixes
  type: subnet      # <-- One of: ip-address, subnet, ip-in-subnet

cat << 'EOF' | kubectl apply -f -
apiVersion: netbox.eda.nokia.com/v1alpha1
kind: Allocation
metadata:
  name: netbox-isl-pool
  namespace: eda
spec:
  enabled: true
  instance: netbox  # <-- Reference to the Instance resource
  tags:
    - eda-isl-pool  # <-- Must match tags on NetBox prefixes
  type: subnet      # <-- One of: ip-address, subnet, ip-in-subnet
EOF

The name of the Allocation resource will drive the name of the EDA allocation pool.

With tags a user selects which tagged Prefixes from NetBox would be "mapped" to this Allocation resource. Since NetBox prefixes don't have a unique name, the tags are used to identify the Prefixes.

A single NetBox prefix object can be mapped to three different allocation pools in EDA depending on the type specified in the Allocation resource.

Consult with the Supported Objects section to see what status a NetBox prefix must have to be compatible with the desired allocation pool type.

The status field of the Allocation resource is used to track the matching allocations. For example, consider the following status block in the Allocation resource:

apiVersion: netbox.eda.nokia.com/v1alpha1
kind: Allocation
metadata:
  name: nb-systemip-v4
  namespace: eda
  labels: {}
  annotations: {}
spec:
  enabled: true
  instance: netbox
  tags:
    - eda-systemip-v4
  type: ip-address
  description: ''
  subnetLength: null
status:
  matchedPrefixes:
    - id: 3
      prefix: 192.168.10.0/24
      tags:
        - eda-systemip-v4
  lastEvent: ''
  lastEventStatus: ''
  lastEventTime: null

It indicates that the incoming via Webhook NetBox prefix 192.168.10.0/24 tagged with the eda-systemip-v4 tag was recorded with the ID 3 for this Allocation resource.

Example#

In this example, we will demonstrate how EDA/NetBox integration works by creating two Prefix objects in NetBox for System IPs and inter-switch link subnets that will be synchronized to EDA and result in two Allocation pools in EDA.
The two pools will then be used to instantiate a Fabric in EDA and through that we will

We will install a demo NetBox instance¹ in the same cluster that runs EDA using helm and the netbox chart v6.0.33:

helm install netbox-server oci://ghcr.io/netbox-community/netbox-chart/netbox \
    --create-namespace \
    --namespace=netbox \
    --set superuser.password=netbox \
    --set enforceGlobalUnique=false \ #(1)!
    --version 6.0.33 #(2)!

1. enforceGlobalUnique=false allows configures the global VRF of NetBox to allow duplicate IP addresses. The duplicated IP addresses may be created by EDA when distinct topologies use the same IP addressing.
2. We fix the chart version to ensure the reproducibility of the example, but there is no hard dependency on the chart version.

The NetBox instance will take a few minutes to start, you can monitor the pods in the netbox namespace² and once all pods are up and running, expose the NetBox instance:

kubectl -n netbox port-forward svc/netbox-server 45123:80

You should now be able to login to the NetBox UI via http://localhost:45123 using admin:netbox credentials.

Then install the NetBox EDA app using one of the documented methods.

NetBox configuration

Webhook

Go to Operations → Integrations → Webhook in NetBox UI and create a webhook with the following values:

• Name: eda

• URL: https://${EDA_ADDR}:${EDA_PORT}/core/httpproxy/v1/netbox/webhook/eda/netbox
  Replace ${EDA_ADDR} and ${EDA_PORT} with the address and port of the EDA instance you use.

• Secret: eda

• SSL verification: disabled

Event Rule

Go to Operations → Integrations → Event Rules in NetBox UI and create an Event Rule that will trigger the Webhook with the following fields set:

• Name: eda
• Object types:
  • IPAM > IP Address
  • IPAM > Prefix
• Enabled: checked
• Event types: Object created Object deleted Object updated
• Action type: Webhook
• Webhook: eda (the name of the webhook we created above)

API Token and Permissions

Normally you would generate a new API token for the user you want to use for API access, but since the demo instance of NetBox that we installed with the Helm chart already contains an API token for the admin user, we will just use it, instead of generating a new one.

Create secrets

Now we need to create the Kubernetes secrets for the generated API Token and the Webhook signature secret.

The inputs to the secrets should be in base64 format, therefore the snippets below run the raw inputs through base64 command to convert them to base64 format.

We install the secrets in the eda namespace - the default namespace your EDA installation comes with. If you use another namespace, adjust the namespace name accordingly.

NETBOX_API_TOKEN=$(kubectl -n netbox get secret netbox-server-superuser -o jsonpath='{.data.api_token}')
cat << EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: netbox-api-token
  namespace: eda
type: Opaque
data:
  # base64-encoded NetBox API token with IPAM permissions
  apiToken: ${NETBOX_API_TOKEN}
EOF

NETBOX_WEBHOOK_SIGNATURE_KEY=$(echo -n "eda" | base64)
cat << EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: netbox-webhook-signature
  namespace: eda
type: Opaque
data:
  # base64-encoded signature key that NetBox will use
  signatureKey: ${NETBOX_WEBHOOK_SIGNATURE_KEY}
EOF

NETBOX_API_TOKEN=$(base64 <<< "yourTokenHere")
cat << EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: netbox-api-token
  namespace: eda
type: Opaque
data:
  # base64-encoded NetBox API token with IPAM permissions
  apiToken: ${NETBOX_API_TOKEN}
EOF

Prefixes and Tags

As per the task of this example we need to create two prefixes in NetBox, one for the System IPs and one for the subnets used by our Fabric app to assign addresses on the point-to-point interswitch links.

We will also create a tag for each of the prefixes, such that we can use the tags to identify each prefix in EDA's Allocation resource.

Starting with the System IPs prefix, we first create a Tag using the Customization → Tags NetBox menu, we will name the tag simply eda-systemip-v4.
Then create a prefix in IPAM → Prefixes NetBox menu and specify the 192.168.10.0/24 prefix with the Status=Active and assign the eda-systemip-v4 tag to it.

Next, we need to create a Prefix for our interswitch links. In EDA, the Fabric app uses the allocation pool of type "subnet" to then assign point-to-point addresses to each end of the interswitch link. This means, that the Prefix in NetBox would need to be created with the Container status, as this would indicate that the Prefix is a container for sub-prefixes. Exactly what we need.

We create the eda-isl-v6 tag first and then the Prefix 2005::/64 with the Status=Container and this tag assigned.

EDA configuration

Switching to EDA. Install the NetBox app if you haven't done already and proceed with creation of the NetBox Instance resource as per the documentation.

We are using the names of the Kubernetes secrets we created a moment ago for the API Token and the Webhook signature key. And since we deployed the NetBox inside the same cluster, we know the DNS name of the service it uses.

apiVersion: netbox.eda.nokia.com/v1alpha1
kind: Instance
metadata:
  name: netbox
  namespace: eda
spec:
  url: http://netbox-server.netbox.svc.cluster.local
  apiToken: netbox-api-token
  signatureKey: netbox-webhook-signature

cat << 'EOF' | kubectl apply -f -
apiVersion: netbox.eda.nokia.com/v1alpha1
kind: Instance
metadata:
  name: netbox
  namespace: eda
spec:
  url: http://netbox-server.netbox.svc.cluster.local
  apiToken: netbox-api-token
  signatureKey: netbox-webhook-signature
EOF

Shortly after submitting the instance resource, you should see EDA reporting the instance as reachable in the status field of the instance resource. Verify with:

kubectl get instance netbox -n eda \
-o custom-columns="URL:.spec.url,STATUS:.status.reachable"

URL                                             STATUS
http://netbox-server.netbox.svc.cluster.local   true

Allocations

Once the Instance resource is configured and the NetBox is reachable, you can proceed with creating the Allocation resources.

As per our task, we need two Allocation Pools in EDA:

1. IPAllocationPool for the IPv4 addresses used as System IPs for our leaf and spines
2. SubnetAllocationPool for the subnets used for the interswitch links in our fabric.

Instead of creating these pools manually, we will create two Allocation resources from the EDA NetBox app and let it create these pools for us based on the NetBox prefixes.

Starting with the Allocation resource for the System IPs:

apiVersion: netbox.eda.nokia.com/v1alpha1
kind: Allocation
metadata:
  name: nb-systemip-v4
  namespace: eda
spec:
  enabled: true
  instance: netbox
  tags:
    - eda-systemip-v4
  type: ip-address

cat << 'EOF' | kubectl apply -f -
apiVersion: netbox.eda.nokia.com/v1alpha1
kind: Allocation
metadata:
  name: nb-systemip-v4
  namespace: eda
spec:
  enabled: true
  instance: netbox
  tags:
    - eda-systemip-v4
  type: ip-address
EOF

The name of the Allocation resource (nb-systemip-v4) will drive the name of the EDA Allocation Pool name once NetBox app will get to create the pool based on the received webhook from the NetBox server.

In the specification block of the Allocation resource we provide

• the name of the NetBox instance resource we just created
• the tags to match the received prefixes from the NetBox server and associate with this Allocation. Recall, that we created this tag in NetBox and added it to the Prefix we intend to use for the System IPs.
• the type of the allocation, which will drive the type of the EDA Allocation Pool. Since System IPs are plain IPv4 addresses, we choose ip-address type.

Following the same approach, create the Allocation resource for the subnets used for the interswitch links:

apiVersion: netbox.eda.nokia.com/v1alpha1
kind: Allocation
metadata:
  name: nb-isl-v6
  namespace: eda
spec:
  enabled: true
  instance: netbox
  subnetLength: 127
  tags:
    - eda-isl-v6
  type: subnet

cat << 'EOF' | kubectl apply -f -
apiVersion: netbox.eda.nokia.com/v1alpha1
kind: Allocation
metadata:
  name: nb-isl-v6
  namespace: eda
spec:
  enabled: true
  instance: netbox
  subnetLength: 127
  tags:
    - eda-isl-v6
  type: subnet
EOF

The difference between the two Allocation resources is the type of the allocation. Since subnets are CIDR blocks, we choose the subnet type and we also specify the subnetLength property to define the length of the subnet to allocate from the received prefix.

Once you have the Allocation resources created, you should see the pools with the matching names created in EDA:

kubectl -n eda get ipallocationpool nb-systemip-v4

NAME             AGE
nb-systemip-v4   13h

kubectl -n eda get subnetallocationpool nb-isl-v6

NAME        AGE
nb-isl-v6   13h

Fabric

Next we create a fabric resource using the EDA Playground topology setup in this example. We reference the allocation pools our NetBox app created when it synced the prefixes:

apiVersion: fabrics.eda.nokia.com/v1alpha1
kind: Fabric
metadata:
  name: my-nb-ebgp-fabric
  namespace: eda
spec:
  leafs:
    leafNodeSelector:
      - eda.nokia.com/role=leaf
  spines:
    spineNodeSelector:
      - eda.nokia.com/role=spine
  interSwitchLinks:
    linkSelector:
      - eda.nokia.com/role=interSwitch
    poolIPV6: nb-isl-v6
  systemPoolIPV4: nb-systemip-v4
  underlayProtocol:
    bgp:
      asnPool: asn-pool
    protocol:
      - EBGP
  overlayProtocol:
    protocol: EBGP

cat << 'EOF' | kubectl apply -f -
apiVersion: fabrics.eda.nokia.com/v1alpha1
kind: Fabric
metadata:
  name: my-nb-ebgp-fabric
  namespace: eda
spec:
  leafs:
    leafNodeSelector:
      - eda.nokia.com/role=leaf
  spines:
    spineNodeSelector:
      - eda.nokia.com/role=spine
  interSwitchLinks:
    linkSelector:
      - eda.nokia.com/role=interSwitch
    poolIPV6: nb-isl-v6
  systemPoolIPV4: nb-systemip-v4
  underlayProtocol:
    bgp:
      asnPool: asn-pool
    protocol:
      - EBGP
  overlayProtocol:
    protocol: EBGP
EOF

The Fabric app will use the referenced pools and will try to allocated the pool resources in order to instantiate a fabric. In our example the System IP (v4) and Subnets (v6) will be allocated from the pools and the allocated resources will be populated back to the NetBox server to keep track of the allocated resources.

From the Prefix we created for System IPs you will see the three allocated IPs populated back in NetBox server, one per each spine and leaf in our topology:

In the same way, you will see interswitch subnets carved out from the 2005::/64 prefix, one per each link between leafs and spines:

Custom Fields

The NetBox app also creates some custom fields in NetBox model to backtrack the allocation of the resources. For example, if you select an allocated sub-prefix from the 2005::/64 prefix, you will see EDA custom fields that show the Allocation resource that created this allocation and the owner object that requested the allocation.

The objects allocated by EDA will also have the EDAManaged tag assigned to them.