Routing Peer

Updated August 3, 2026

The operator exposes Kubernetes services to your NetBird network by combining two resources, a NetworkRouter and a NetworkResource.

NetworkRouter

A NetworkRouter creates a network in NetBird and deploys routing peer pods in the cluster. These pods are configured as routing peers for the network, handling traffic between NetBird clients and services running in the cluster.

Before creating a NetworkRouter, you must first create a custom DNS zone in the NetBird dashboard. The DNS zone must exist before the operator can register it.

apiVersion: netbird.io/v1alpha1
kind: NetworkRouter
metadata:
  name: prod
  namespace: netbird
spec:
  dnsZoneRef:
    name: prod.company.internal

NetworkResource

A NetworkResource exposes a Kubernetes service in NetBird by creating a matching resource in the routers network. The cluster IP of the service will be used as the resource IP. A record in the routers zone will also be created using the name and namespace of the service. The following example creates an nignx deployment and exposes the service with the record nginx.default.prod.company.internal.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  namespace: default
  labels:
    app: nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  strategy:
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
    type: RollingUpdate
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx
        imagePullPolicy: Always
        name: nginx
---
apiVersion: v1
kind: Service
metadata:
  name: nginx
  namespace: default
  labels:
    app: nginx
spec:
  type: ClusterIP
  ports:
  - name: http
    port: 80
    protocol: TCP
    targetPort: 80
  selector:
    app: nginx
---
apiVersion: netbird.io/v1alpha1
kind: NetworkResource
metadata:
  name: nginx
  namespace: default
spec:
  networkRouterRef:
    name: prod
    namespace: netbird
  serviceRef:
    name: nginx
  groups:
    - name: All

Members of the All NetBird group can now reach the nginx service at nginx.default.prod.company.internal through the NetBird network.

NetworkEgress

The network router can also be used for egress traffic to reach other peers within the NetBird network. The network egress resource defines the target and links it to a network router. The target can either be a FQDN hostname or an IP address. Generally using a hostname is preferable especially if the target resource is hosted in another Kubernetes cluster. Egress through the network router works by assigning a random destination port for each network egress resource. This way the destination address and port can be rewritten before reaching the tunnel. Native Kubernetes services are used for directing the traffic to the network router, meaning normal service discovery can be used for external peers.

Create a network egress resource in the namespace where it will be consumed. The operator will create an accompanying service with the same name for the egress resource. In this example the target is the nginx deployment from the network resource example.

apiVersion: netbird.io/v1alpha1
kind: NetworkEgress
metadata:
  name: nginx
  namespace: default
spec:
  networkRouterRef:
    name: prod
    namespace: netbird
  target:
    fqdn:
      hostname: nginx.default.prod.company.internal
  ports:
    - name: http
      port: 80

Once the network egress resource has been reconciled an HTTP request to nginx.default.svc.cluster.local. should reach the external resource.