Metadata overview

Stores and services engine metadata.

Metadata service

The metadata service stores and serves engine metadata. It uses PostgreSQL as the backing database. Engines connect to it at startup and during operation so they can read the account and engine state they need to run queries.

Experimental: spec.metadataNG: true selects metadata-ng configuration and UID/GID, but does not select the metadata image. When imagePullPolicy is unset it also defaults the metadata container to Always, so a floating tag such as pd-dev is re-pulled instead of pinning a node to its first cached digest. Legacy behavior remains the default.

The two services read different configuration documents. The legacy service reads a pensieve_lite document; metadata-ng reads a pensieve_duck document carrying only the listen address and the PostgreSQL host, port, and database, and rejects any other key at startup. spec.id and spec.metadata.postgres.schema are not rendered for metadata-ng: the service is isolated by the configured database and lays its catalog out across its own schemas inside it, so a custom schema has no effect with metadataNG: true.

External PostgreSQL TLS

To verify an external PostgreSQL server certificate and hostname, configure spec.metadata.postgres.tls:

spec:
  metadata:
    postgres:
      host: postgres.example.com
      database: metadata
      credentialsSecretRef:
        name: postgres-credentials
      tls:
        mode: verify-full
        caSecretRef:
          name: postgres-ca
          key: ca.crt

Create the CA Secret in the FireboltInstance namespace. The Firebolt Operator mounts only the selected key into the Metadata container. Updating the credentials Secret or CA Secret rolls the Metadata pod.

Rolling update parameters

Metadata deployment

Parameter	Value	Rationale
maxSurge	0	Never run two metadata pods concurrently. The metadata service assumes single-writer against Postgres
maxUnavailable	1	Old pod is terminated before the new one starts. Brief metadata-unavailable window during rollouts
Replicas	1 (enforced by webhook)	Multi-replica metadata is not currently supported