Creating a LoadBalancer Service#

Set type: LoadBalancer in your Service spec. PureLB watches for these services and allocates addresses automatically.

Basic IPv4 Service#

apiVersion: v1
kind: Service
metadata:
  name: my-app
spec:
  type: LoadBalancer
  selector:
    app: my-app
  ports:
  - port: 80
    targetPort: 8080

Dual-Stack Service#

apiVersion: v1
kind: Service
metadata:
  name: my-app
  annotations:
    purelb.io/service-group: default
spec:
  type: LoadBalancer
  ipFamilyPolicy: PreferDualStack
  ipFamilies:
  - IPv4
  - IPv6
  selector:
    app: my-app
  ports:
  - port: 80
    targetPort: 8080

PreferDualStack works on both single-stack and dual-stack clusters.

Annotations#

Selecting a ServiceGroup#

annotations:
  purelb.io/service-group: routed

If omitted, PureLB uses the ServiceGroup named default.

Requesting a Specific Address#

annotations:
  purelb.io/addresses: "192.168.1.100"

For dual-stack, comma-separate the addresses:

annotations:
  purelb.io/addresses: "192.168.1.100,fd00:1::100"

The requested address must be within the ServiceGroup’s pool range.

Sharing an IP Address#

Multiple services can share a single IP if they use different ports. Set the same sharing key on each service:

# Service A
annotations:
  purelb.io/allow-shared-ip: "my-shared-vip"
---
# Service B
annotations:
  purelb.io/allow-shared-ip: "my-shared-vip"

ExternalTrafficPolicy is forced to Cluster for shared addresses.

ExternalTrafficPolicy Local#

externalTrafficPolicy: Local is supported for remote address pools only. This enables Direct Server Return (DSR): traffic arrives at the node and is delivered directly to the pod without traversing the CNI or being rewritten by kube-proxy. The original client source IP and destination address are preserved end-to-end. PureLB only adds the address to nodes running target pods, so BGP only advertises routes from those nodes.

apiVersion: v1
kind: Service
metadata:
  name: my-app
  annotations:
    purelb.io/service-group: routed
spec:
  type: LoadBalancer
  externalTrafficPolicy: Local
  selector:
    app: my-app
  ports:
  - port: 80
    targetPort: 8080

For local address pools, PureLB always uses externalTrafficPolicy: Cluster. If a service with a local pool is set to Local, PureLB resets it to Cluster automatically.

Multi-Pool Override#

Override the ServiceGroup’s multiPool setting for a specific service:

annotations:
  purelb.io/multi-pool: "true"

Force Re-Evaluation#

PureLB evaluates a service once at creation time. If the network environment changes after allocation – for example, nodes are added to new subnets, ServiceGroup pools are expanded, or multi-pool ranges are updated – existing services won’t automatically pick up the changes.

The re-evaluate annotation triggers PureLB to reprocess the service as if it were newly created:

annotations:
  purelb.io/re-evaluate: "true"

This is a one-shot trigger – PureLB deletes the annotation after processing. The service retains its existing addresses but may gain additional addresses (e.g., from newly-available multi-pool ranges) or be validated against updated pool configuration.

Common use cases:

• A new subnet was added to a multiPool ServiceGroup and existing services need addresses on the new subnet.
• A pool was expanded and you want to verify services are still correctly allocated.
• Node topology changed and you want election re-evaluation.

Kubernetes Service Fields#

Reading Service Status#

PureLB adds informational annotations to allocated services:

kubectl describe svc my-app

Annotations:  purelb.io/allocated-by: PureLB
              purelb.io/allocated-from: default
              purelb.io/pool-type: local
              purelb.io/announcing-IPv4: node1,enp1s0
              purelb.io/service-group: default

For detailed inspection, use the kubectl plugin:

kubectl purelb inspect default/my-app

Complete Annotation Reference#

See the Annotations Reference for the full list.