Hubble traffic relay repository boundary

3 min read

Hubble traffic relay repository boundary

Context

The Hubble traffic stream crosses three execution boundaries:

  1. a Go producer in Devata reads allowlisted aggregate Prometheus series;
  2. a TypeScript Cloudflare Worker validates, retains, and streams those aggregates;
  3. the portfolio consumes the public stream after the producer and relay are verified.

The Worker runs on Cloudflare, not Kubernetes. Its source is nested beside the Kubernetes workload because the payload schema, authentication rules, release workflow, and rollout order currently form one feature contract. That placement raised a valid ownership question because lab is primarily the declarative source for Devata.

Decision

Keep the producer, relay, and their delivery workflow together in lab for this feature.

  • The Go producer and Kubernetes resources remain under the showcase application.
  • The TypeScript relay remains in the same feature directory but is deployed only by GitHub Actions to Cloudflare Workers.
  • The portfolio consumer remains a separate change in pragalva-s-platform-hub; PR #64 added it only after live verification.
  • The public architecture decision in PR #61 remains the canonical explanation of the stream design. This private record explains only the repository boundary.

This is a deliberate exception for one tightly coupled feature, not a rule that all external application code belongs under kubernetes/.

Why

  • Producer and relay changes can update the closed payload and authentication contract atomically.
  • One pull request can validate the Go producer, Worker, manifests, and deployment wiring before any consumer depends on them.
  • A separate relay repository would add another release boundary, credential setup path, and cross-repository sequencing requirement before the relay has an independent lifecycle.
  • The existing workflow already separates Kubernetes validation from the Go and TypeScript source trees.

Consequences

  • lab owns one off-cluster Cloudflare deployment in addition to Devata’s declarative state.
  • The directory path does not imply that TypeScript executes in the cluster; the Worker is an external relay.
  • Cloudflare account state and credentials remain external dependencies. Credentials stay outside Git and the in-cluster producer credential stays sealed.
  • PRs #61 and #63 are merged. On 2026-08-01, the producer was Ready with zero restarts, Argo was Synced/Healthy, public history contained fresh five-second samples, and a WebSocket client received both the latest sample and the next live sample. Platform-hub PR #64 then added the consumer and production browser proof covered live updates, reconnecting, stale snapshot fallback, and recovery. streaming-aggregate-hubble-traffic records the complete case.

Revisit when

Move the relay to a dedicated repository when at least one of these becomes true:

  • it gains an independent release cadence or owner;
  • it serves another workload or contract;
  • Cloudflare resources move under a broader OpenTofu ownership model;
  • its code grows beyond a narrow validation, retention, and streaming adapter;
  • changes routinely require cross-feature coordination rather than an atomic producer and relay update.