Velocity Docs

Integration guide

Blend Velocity with existing gateways, APIs, and service meshes without disrupting users.

Last updated October 8, 2025View on GitHub

Bring Velocity into your stack

Velocity coexists with classical TLS. This guide shows how to introduce it gradually, keep fallbacks healthy, and expose metrics so product teams keep their visibility.

Integration playbook

GoalPatternNotes
Validate in production quietlyShadow mirrorPassively mirror a slice of traffic via UDP pass-through (Envoy, HAProxy). Analyse downgrades before sending real users.
Roll out to a subset of usersGradual cutoverRoute 5–10% of authenticated sessions through Velocity, watch handshake p95 and success rate, then expand.
Feed internal meshesMesh bridgeTerminate Velocity at the edge, forward HTTP/3 to Istio/Linkerd/Consul. Preserve mTLS between mesh workloads.

Every pattern keeps HTTP/3 fallback alive. Make sure you can flip traffic back to the classical path by toggling weights or DNS.

Wire traffic safely

  1. Document entry points—decide which domains receive Velocity first and which stay on legacy HTTPS.
  2. Expose UDP pass-through on your load balancer. Envoy listeners, HAProxy bind ... transport=quic, or Cloud LB UDP forwarding all work.
  3. Tag requests with alpn, profile, and workload so observability matches what app teams expect.
  4. Teach on-call responders how to trigger fallback-only mode (velocity-cli admin policy --downgrade-all) in case a client upgrade is delayed.

Automation touchpoints

  • Admin API: script quiesce/resume for maintenance, ticket rotation, and config reloads.
  • Edge runtime (edge.yaml): add rate limits, auth middleware, and templated health endpoints without redeploying binaries.
  • CI pipelines: run velocity-cli config lint and a subset of integration smoke tests before promoting changes.

Telemetry to forward

  • Export metrics into Prometheus or your preferred backend. Focus on handshake latency, downgrade counters, and ticket churn.
  • Stream structured logs to your data lake. Filter on connection_id, profile, and downgrade_reason when debugging.
  • Feed Velocity’s tracing metadata into your existing span collectors so distributed traces remain intact.

Cutover checklist

  1. Pilot traffic mirror shows downgrade ratio < 5% and no fatal errors.
  2. Application latency budgets stay flat relative to the control group.
  3. Monitoring dashboards include Velocity metrics alongside app SLOs.
  4. Run incident drills: fail open to HTTP/3, revoke and rotate tickets, and restore normal service.
  5. Capture learnings and feed them into the Upgrade guide for future releases.