Configure Broker Per-Pod Networking

This guide explains how to configure per-pod networking for PulsarBroker using networking.podService and advertisedListeners.

Overview

Two features work together to enable per-pod access:

Feature	Purpose
`networking.podService`	Creates a dedicated Kubernetes Service for each broker pod
`advertisedListeners`	Configures brokers to advertise custom addresses to clients

Use cases:

Istio Federation / Multi-cluster communication
Direct pod access scenarios

Configuration

Example

apiVersion: pulsar.streamnative.io/v1alpha1
kind: PulsarBroker
metadata:
  name: pulsar
  namespace: pulsar
spec:
  # Enable per-pod services
  networking:
    podService:
      enabled: true
      type: ClusterIP
      annotations:
        example.com/pod-service: "true"

  # Use per-pod service DNS as advertised listener
  # Note: Use non-default port (6660) to avoid conflict with brokerServicePort (6650)
  advertisedListeners:
    - name: pod
      hostTemplate: "$(POD_NAME).pulsar.svc.cluster.local"
      protocols:
        pulsar:
          containerPort: 6660
          advertisedPort: 6660

Configuration Reference

networking.podService

Field	Type	Default	Description
`enabled`	bool	`false`	Enable per-pod Service creation
`type`	string	`ClusterIP`	Service type: `ClusterIP`, `LoadBalancer`, or `NodePort`
`annotations`	map	`{}`	Annotations to add to each pod Service

advertisedListeners

Field	Type	Description
`name`	string	Unique identifier for this listener
`hostTemplate`	string	Hostname template, supports `$(POD_NAME)` and `$(POD_ID)`
`protocols.pulsar.containerPort`	int	Port the broker container listens on
`protocols.pulsar.advertisedPort`	int	Port advertised to clients

Use a non-default port (e.g., 6660) to avoid conflict with the default brokerServicePort (6650).

A Pulsar client first looks up which broker owns a topic, then connects directly to that broker at the address the lookup returned. Every broker must therefore be reachable at its own address.Always include $(POD_NAME) or $(POD_ID) in hostTemplate. A template without one of these variables makes every broker advertise the same address. Clients then reach a random broker on each attempt and loop on:

ServiceNotReady: Namespace bundle (...) not served by this instance: ... Please redo the lookup.

See Verify Advertised Addresses to confirm your template is correct.

Verify Configuration

Check Created Services

kubectl get svc -n pulsar | grep broker

Expected output:

pulsar-broker            ClusterIP   10.0.0.1   <none>   6650/TCP,8080/TCP
pulsar-broker-0          ClusterIP   10.0.0.2   <none>   6650/TCP,6660/TCP,8080/TCP
pulsar-broker-1          ClusterIP   10.0.0.3   <none>   6650/TCP,6660/TCP,8080/TCP

Verify Service Selector

kubectl get svc pulsar-broker-0 -n pulsar -o jsonpath='{.spec.selector}'

Expected: {"statefulset.kubernetes.io/pod-name":"pulsar-broker-0"}

Verify Advertised Addresses

Each broker must advertise its own address. Compare two brokers:

kubectl exec -n pulsar pulsar-broker-0 -- env | grep PULSAR_PREFIX_advertisedListeners
kubectl exec -n pulsar pulsar-broker-1 -- env | grep PULSAR_PREFIX_advertisedListeners

The entry for your listener must name a different host in each output, for example pulsar-broker-0.pulsar.svc.cluster.local and pulsar-broker-1.pulsar.svc.cluster.local. If both brokers show the same host, hostTemplate is missing $(POD_NAME) or $(POD_ID), and clients will not be able to reach individual brokers.

Test Connectivity

kubectl run test-client --image=curlimages/curl:latest --rm -it --restart=Never -n pulsar -- \
  curl -s http://pulsar-broker-0:8080/admin/v2/brokers/healthcheck

Overview

Quick Start

Configure Private Cloud

Operate Private Cloud

References

Overview

Configuration

Example

Configuration Reference

networking.podService

advertisedListeners

Verify Configuration

Check Created Services

Verify Service Selector

Verify Advertised Addresses

Test Connectivity

​Overview

​Configuration

​Example

​Configuration Reference

​networking.podService

​advertisedListeners

​Verify Configuration

​Check Created Services

​Verify Service Selector

​Verify Advertised Addresses

​Test Connectivity

Overview

Configuration

Example

Configuration Reference

networking.podService

advertisedListeners

Verify Configuration

Check Created Services

Verify Service Selector

Verify Advertised Addresses

Test Connectivity