Skip to content
Operating puddle

Operating puddle

What to know to run puddle for real, beyond the configuration reference. Start with Getting started for a first catalog.

  • High availability and replicas: which metastore allows several replicas, what is safe to run concurrently, and rolling restarts.
  • Security hardening: TLS, authentication and authorization, vended credentials, locations, what the public endpoints expose, secrets.
  • Backup and restore: the metastore and the warehouse, and keeping them consistent.
  • Upgrades: what to expect between versions while puddle is pre-release.
  • Timeouts and purge: request deadlines, dropping tables with purge, and what happens to files.
  • Observability: logs and request ids, decision logs, and OpenTelemetry metrics, traces and alerts.

A production checklist

  • A release, pinned by version or digest, with its signature verified.
  • PostgreSQL metastore for more than one replica; SQLite only with exactly one.
  • Object storage (S3 or compatible) for the warehouse, with no lifecycle rule that expires objects under it.
  • TLS in front of puddle; only /api/catalog/ exposed to clients.
  • authn: configured (JWT or static tokens) and an authz: policy (OPA or CEL) that fits your principals.
  • Credential vending, so engines never hold the catalog’s own storage keys.
  • No unrestricted-locations on any warehouse.
  • Every secret in the config as ${VAR}.
  • shutdown-timeout inside the platform’s termination grace period.
  • Backups of the metastore and the warehouse, restored at least once.
  • Logs collected as JSON (logging.format: json), searchable by request_id.
  • telemetry on, /metrics scraped from the management listener (kept off the clients’ network), traces sampled to a collector, and the suggested alerts.