Pulsar Detector

The Pulsar detector checks HTTP access and message production and consumption. Use its latency measurements and availability gauges with Prometheus and Grafana to monitor a cluster or connections across clusters.

Enable the detector

Configure endpoints on the PulsarCoordinator CR:

spec:
  detector:
    serviceEndpoint:
      pulsarServiceURL: pulsar://brokers-broker-headless:6650
      webServiceURL: http://brokers-broker-headless:8080

Use endpoints reachable from the detector Pod. For a TLS-enabled deployment, configure the TLS endpoints and the detector image’s required TLS trust settings. The broker’s authentication configuration does not automatically configure the detector’s credentials.

Configure a projected ServiceAccount token

Upgrade to StreamNative Operator Helm chart 0.20.6 (Operator v0.20.18) and update its CRDs before using this example. This release supports detector-specific resources, ServiceAccounts, volumes, and volume mounts under spec.detector.pod, and preserves custom volumes and mounts alongside broker authentication volumes. See Upgrade StreamNative Operator. The detector also needs a runtime that supports token-file authentication and reloads the file when it changes. These are separate requirements from the Operator’s Pod configuration support.

The detector packaged in Private Cloud Pulsar 4.2.1.17 still fails with No token provided when given the JSON file parameter below. Upgrading the Operator to v0.20.18 does not fix that detector runtime. Select a detector image whose token-file behavior you have verified before using this configuration for rotating tokens.

Create a ServiceAccount with the required Pulsar permissions, and merge this configuration into the Coordinator. Replace the image placeholder with a validated image and make the audience match the broker’s OIDC configuration:

spec:
  detector:
    image: "<validated-detector-image>"
    serviceEndpoint:
      pulsarServiceURL: pulsar://brokers-broker-headless:6650
      webServiceURL: http://brokers-broker-headless:8080
    clientAuth:
      generic:
        authPlugin: token
        authParams: '{"file":"/mnt/detector-oidc/token"}'
    pod:
      serviceAccountName: pulsar-detector
      resources:
        requests:
          cpu: 100m
          memory: 128Mi
      volumes:
        - name: detector-oidc
          projected:
            sources:
              - serviceAccountToken:
                  audience: pulsar-cluster-a
                  expirationSeconds: 600
                  path: token
      volumeMounts:
        - name: detector-oidc
          mountPath: /mnt/detector-oidc
          readOnly: true

The role for this token is system:serviceaccount:<namespace>:pulsar-detector when the OIDC provider uses sub. Configure the permissions required by the detector’s HTTP and messaging checks. See OIDC authentication. spec.detector.pod takes precedence over the Coordinator’s top-level spec.pod for the detector. When the detector-specific policy is absent, the Operator uses the top-level policy as a fallback. If you omit detector resource settings, the Operator keeps its detector resource defaults. The Go detector uses authPlugin: token with JSON authParams. This differs from the Java client’s AuthenticationToken plugin and file:///... parameter. Do not copy Java authentication parameters into the detector configuration.

Verify authentication and token rotation

Inspect the generated detector Deployment. Check its image, ServiceAccount, projected volume, mount path, and authentication arguments. Avoid copying bearer tokens into logs or diagnostics.
With valid credentials, confirm that both availability gauges become 1 and that successful messaging latency samples increase over several detection rounds.
For an isolated test, compare the file parameter with a short-lived literal token from the same identity, using authParams: '{"token":"<short-lived-token>"}'. The detector expects JSON parameters, so a raw JWT string is not valid here. A literal-token success with file-parameter failure identifies a file-authentication problem; it does not provide a rotating-token solution.
With an image that supports file authentication, replace a test token file atomically with an invalid token and confirm detection failures. Restore a valid token and require the same detector process to resume successful rounds.
Observe a real Kubernetes projected-token rotation and confirm that detection continues after the token changes. Kubernetes rotates the volume’s contents; a literal token in a process argument does not rotate with that volume.

Do not treat Pod Ready, Coordinator Ready, or an accessible metrics endpoint as proof that authentication or SLA checks succeed. The 4.2.1.17 file-authentication failure leaves the metrics endpoint accessible while the availability gauges stay at 0.

Metrics

Check the metrics exposed by your deployed detector image. The 4.2.1.17 runtime exposes the following names:

Name	Type	Description
`pulsar_detector_e2e_latency_ms`	Summary	Latency from message publication to consumption.
`pulsar_detector_publish_latency_ms`	Summary	Message publication latency.
`pulsar_detector_pulsar_sla_messaging_up`	Gauge	`1` when the messaging check succeeds; `0` when it fails.
`pulsar_detector_pulsar_sla_webservice_up`	Gauge	`1` when the HTTP check succeeds; `0` when it fails.

Latency summaries include a success label and _count and _sum series. Verify successful samples as well as the gauges. Historical dashboards may use shorter SLA metric names; align queries with the names returned by your runtime.

Overview

Quick Start

Configure Private Cloud

Operate Private Cloud

References

Enable the detector

Configure a projected ServiceAccount token

Verify authentication and token rotation

Metrics

​Enable the detector

​Configure a projected ServiceAccount token

​Verify authentication and token rotation

​Metrics

Enable the detector

Configure a projected ServiceAccount token

Verify authentication and token rotation

Metrics