ContainerSource

yipyap-knative-source is a small Go binary published at ghcr.io/yipyap-run/knative-source-receive-adapter that runs inside your Kubernetes cluster as a Knative ContainerSource. It connects outbound to YipYap, receives CloudEvents, and forwards them to the K_SINK URL Knative injects, your Broker, a specific Service, any CloudEvents-compatible consumer.

Use this when:

• You can’t expose your Broker URL to the public internet.
• You prefer pull-based ingestion over push webhooks.
• You need deterministic cursor resume across restarts.

Install

Minimal ContainerSource:

apiVersion: v1
kind: Secret
metadata:
  name: yipyap-source-api-key
  namespace: yipyap
type: Opaque
stringData:
  YIPYAP_API_KEY: yy_your_org_scoped_api_key
---
apiVersion: sources.knative.dev/v1
kind: ContainerSource
metadata:
  name: yipyap-alerts
  namespace: yipyap
spec:
  template:
    spec:
      containers:
        - image: ghcr.io/yipyap-run/knative-source-receive-adapter:1.1.1
          env:
            - name: YIPYAP_API_KEY
              valueFrom:
                secretKeyRef:
                  name: yipyap-source-api-key
                  key: YIPYAP_API_KEY
            - name: YIPYAP_EVENT_FILTER
              value: "run.yipyap.alert.*"
          livenessProbe:
            httpGet:
              path: /healthz
              port: 8080
  sink:
    ref:
      apiVersion: eventing.knative.dev/v1
      kind: Broker
      name: default
  ceOverrides:
    extensions:
      environment: prod

Copy from deploy/knative/containersource.yaml.

Environment variables

Knative injects K_SINK (the destination URL) and K_CE_OVERRIDES (a JSON blob of extension attributes to layer onto every forwarded event) automatically. You provide the yipyap-specific bits:

Variable	Default	Purpose
YIPYAP_API_KEY	required	Org-scoped API key from the YipYap UI.
YIPYAP_BASE_URL	https://console.yipyap.run	Override for self-hosted FOSS deployments.
YIPYAP_EVENT_FILTER	""	path.Match glob over CloudEvent type. run.yipyap.alert.* narrows to alert events.
YIPYAP_MODE	"" (auto)	poll, stream, or empty. See mode selection below.
YIPYAP_POLL_INTERVAL	5s	Polling cadence in poll mode.
YIPYAP_CURSOR_PATH	/var/run/yipyap/cursor	Resume-cursor persistence path (in poll mode). Mount a writable volume.
YIPYAP_HEALTH_ADDR	:8080	Health-check listen address for /healthz and /readyz.

Mode selection

The binary chooses between poll-mode and stream-mode with precedence (highest wins):

1. YIPYAP_MODE env, set on the pod spec. poll or stream is respected verbatim.
2. CR override file. When you use the YipYapSource CRD, the controller writes /etc/yipyap/source-mode. If you are driving the binary via ContainerSource, you can skip this.
3. Server hint. GET /api/v1/knative/source-config returns {recommended_mode, poll_interval_seconds, refresh_after_seconds}. YipYap can update an org’s recommended mode remotely without you redeploying.
4. Ship default, poll with a 5-second interval.

Poll-mode pulls from GET /api/v1/cloudevents/poll and persists a cursor for at-least-once delivery. Stream-mode connects to GET /api/v1/cloudevents/stream and reads NDJSON until disconnect (then reconnects with exponential backoff).

Choose poll unless you have a specific sub-5s latency requirement. Poll is compatible with every NAT, proxy, service mesh, and CDN. Stream is best-effort-lossy on client emit failures (by design, server commits its cursor on stream-write; if your Broker is transiently unavailable, the event is dropped from the stream and the cursor is advanced). Stick with poll for anything important.

Cursor persistence

Poll-mode writes the cursor to YIPYAP_CURSOR_PATH after every successful emit batch. To survive pod restarts, mount a volume at the cursor’s parent directory:

containers:
  - image: ghcr.io/yipyap-run/knative-source-receive-adapter:1.1.1
    volumeMounts:
      - name: cursor
        mountPath: /var/run/yipyap
volumes:
  - name: cursor
    emptyDir: {}

emptyDir is fine for most cases, if the pod restarts on the same node, the cursor survives. For cross-node persistence use a PersistentVolumeClaim. If the cursor is missing, the source resumes from “now” (any events emitted while the pod was down are lost).

Filter expressions

YIPYAP_EVENT_FILTER accepts any pattern supported by Go’s path.Match:

• run.yipyap.alert.*, all alert events (one segment wildcard).
• run.yipyap.monitor.down.v1, exact match.
• “ (empty), deliver every event type.

Multi-type selection isn’t supported in a single binary; deploy multiple ContainerSource objects with different filter globs to fan out by type.

Observability

The binary exposes:

• /healthz, liveness (always 200 after startup).
• /readyz, readiness.
• Structured JSON logs on stdout.

Metrics are not exported by the binary itself (the binary is intentionally lean). YipYap records the server-side yipyap.cloudevents.poll.* and yipyap.cloudevents.stream.* counters; consult your YipYap metrics dashboard for delivery visibility.

Troubleshooting

• 401 on startup → the YIPYAP_API_KEY secret isn’t valid.
• Events aren’t arriving → check YIPYAP_EVENT_FILTER glob. Empty string = deliver everything; a typo = nothing matches.
• Pods keep restarting → check kubectl logs for the binary’s structured error. Missing volume mount is a common cause when poll-mode fails to write the cursor.
• Mode switched unexpectedly → if YIPYAP_MODE is unset, SaaS ops may have flipped the org’s hint. Set the env var explicitly to pin.

What’s next

• Source CRD: the dedicated YipYapSource CRD is richer than ContainerSource and the recommended option for production.
• Architecture, how events flow internally.