droboticflow/deploy/diagnostic-gateway/readonly-data-plan.md

6.7 KiB

Diagnostic data access: proposed production changes

Status: Mongo and logs approved and deployed 2026-11-10; see production-approval-checklist.md and the external guide. IAM/BCM remain deferred by user agreement. The following documents scope and limitations, not a repeatable creation instruction.

Mongo

Target database: drobodata-fanyu. Create dedicated user diagnostic_gateway_reader_v1 with a randomly generated password; store its URI only in a new diagnostic-gateway-mongo-readonly Secret. Never mount the application's Mongo secret into the gateway.

Create four projection-only views and custom role diagnostic_gateway_views_v1. Grant only find on those four view names; no access to source collections, users, sessions, secrets, write commands, administrative commands or other databases. Scope views to the verified production organization org-29cd7a684faba19f630f8ad5890e18bb. These are virtual views, not materialized data copies.

  • diagnostic_tasks_v1 -> annotationTasks: task ID, organization/project/run/workflow IDs, stage-independent task status, revision, supplier/assigned IDs, created/updated timestamps. Exclude video URLs, signed links, labels and all annotation content.
  • diagnostic_items_v1 -> humanItems: item ID, legacy task ID, organization/project/run IDs, stage/status/version/round, assigned/supplier IDs, submitted/updated timestamps, cancellation boolean, presence of pending submission; processingJob ID/kind/status/stage/attempt/nextAttemptAt/leaseUntil/createdAt/updatedAt and slice counts. Exclude subject, input, payload, notes and raw errors.
  • diagnostic_validation_v1 -> annotationIndexJobs: job ID/task ID, organization/project/run IDs, status/attempt/createdAt/nextAttemptAt/revalidateSource, source/superseded fingerprint, and allowlisted error category. Raw error text never leaves the view. Error categories must be conservative: imu_invalid, video_timing_mismatch, source_missing, storage_scope, unknown. A category is not a confirmed root cause.
  • diagnostic_events_v1 -> humanEvents: event ID, organization/item/stage IDs, eventType and occurred timestamp from the actual schema; no event body or customer comments. Verify timestamp field before rendering executable views.

Creation must first inspect existing names and fail on collision; never overwrite an existing view or user. Validate pipelines on isolated fixtures, then use production read-only explain to confirm exact ID predicates use existing indexes. Max 1 task + matching item, <=20 validation IDs/history records, <=50 events; each query maxTimeMS <=1000 and whole request <=3 seconds, max two concurrent database requests, bounded cache. No regex task-name scan, arbitrary Mongo filters, arbitrary pipelines, or dashboard-wide aggregation.

Historical validation through source-v1 jobs must follow actual source identity/supersession contracts; do not assert claim eligibility based solely on one old failed job. Permission-based availability requires the real server business rules and actor evidence; until supported, report actor eligibility as unknown.

Rollback: revoke/drop only the new role/user and four views after disabling the adapter. Do not modify underlying records, validation jobs, tasks, indexes or source files. Creating views/user/role is a production metadata write and requires explicit approval.

Kubernetes logs

Extend the gateway namespace Role with get on pods/log only. Kubernetes RBAC cannot restrict returned log lines or dynamically named pod prefixes: this is wider than the external API. Gateway must resolve pods from current allowlisted deployment labels, not caller-provided URLs/namespaces; no generic proxy or exec.

Initial external log endpoint emits only parsed request_trace fields (request ID, kind, numeric status/elapsed_ms, timestamp and an approved route category). Do not publish raw logs using best-effort regex masking. Unknown lines are counted as omitted; zero returned records never means no error. Time window <=15 minutes, <=200 lines and <=64KiB per pod, <=2 pods per request; forbid follow/stream, bound timeouts and concurrency. Broader processor diagnostics need explicit structured logging contracts first.

Baidu cloud BCM

Create a separate programmatic IAM identity diagnostic_gateway_bcm_reader_v1, with monitoring-data query permission only. Fix region, cloud account identity and the EIP resource corresponding to 120.48.180.80 on the server. Do not grant network configuration, bandwidth changes, security-group changes, alarm mutations, cloud admin or BOS access. Store dedicated AK/SK only in diagnostic-gateway-bcm-readonly Secret.

The installed official BCM SDK provides GetMetricData. The exact IAM action strings and resource-level scoping support have NOT yet been verified from an authoritative policy definition; do not invent an executable IAM policy or silently fall back to account-wide cloud read permissions. Confirm these in the cloud IAM policy editor/documentation before creating the principal. If resource scoping is unsupported, propose a separately isolated collector with fixed metric output and obtain approval for the broader internal read scope.

Collect WebOutBitsPerSecond, WebInBitsPerSecond and documented EIP throttling/drop counters for that exact resource. 60-second sampling, <=1 hour initial history, server-controlled metric list, 60-second shared cache. Return source timestamp/unit/statistic/window, absent/stale status and configured bandwidth separately. Never substitute 50Mbps configuration or summed Pod traffic for actual public egress. Monitor query costs/quotas and do not enable paid telemetry services without approval.

Evidence-only acceptance

Only use the exposed diagnostic endpoint for final investigation. Record returned evidence/timestamps, latency/bytes and conclusion separately for:

  • FYLX_B06_AZER76400JE_19700111_024557/part0001: failed source validation, then exceptional isolation. Deleted drafts/events cannot be recovered or fabricated.
  • FYLX_B11_AZEC86400SC_19700104_182758/part0001: later successful submission does not prove the initial slice-generation failure cause. Missing retained error history must produce insufficient_evidence.
  • FYLX_B02_AZER76400GJ_19700116_013952/part0002: historical first-500 client truncation requires the relevant historical build/client behavior; current task metadata alone cannot prove it.
  • Slow pool/dashboard: correlate current request traces and deployment identity. Do not claim Mongo wait or bandwidth congestion without its measured evidence.

Use synthetic replay for historical evidence no longer retained; label synthetic results explicitly, never present them as live production confirmation. All tests prohibit production mutations. Confirm no source payload/secrets leak, bounded queries and rejection of writes/operator injection/SSRF, credential revocation, upstream timeout and recovery.