Spec reference
Pod configuration for the gateway and metadata components lives on a rawPodTemplateSpec
under spec.gateway.template and spec.metadata.template respectively.
They use the same shape as FireboltEngineClass.spec.template. The validating webhook
restricts what users may set on those templates. See
Firebolt Operator-owned fields
and Customize component pods.
| Field | Required | Default | Description |
|---|---|---|---|
spec.id | No | (auto-generated ULID) | Stable unique identifier for the instance, used as the metadata account ID. Newly minted values are lowercase Crockford ULIDs (uppercase only on an operator build that has no canonicalize floor compiled in). Immutable once set except for a case-only rewrite: the Firebolt Operator lowercases an existing uppercase Crockford ULID after engine and metadata images meet the canonicalize floor. |
spec.metadataNG | No | false | Experimental. Use the metadata-ng configuration and UID/GID. The image remains user-selected. |
spec.metadata | Yes | - | Metadata service configuration (can be empty {} for defaults) |
spec.metadata.postgres | No | (internal) | External PostgreSQL connection. If omitted, the Firebolt Operator deploys an internal PostgreSQL StatefulSet. |
spec.metadata.postgres.host | Yes* | - | PostgreSQL hostname |
spec.metadata.postgres.port | No | 5432 | PostgreSQL port |
spec.metadata.postgres.database | Yes* | - | Database name |
spec.metadata.postgres.credentialsSecretRef.name | Yes* | - | Secret with username and password keys |
spec.metadata.postgres.tls | No | disabled | Require verified TLS for the external PostgreSQL connection. |
spec.metadata.postgres.tls.mode | No | verify-full | libpq TLS mode. Only verify-full is supported. |
spec.metadata.postgres.tls.caSecretRef.name | Yes* | - | Secret containing the CA certificate. The Secret must be in the FireboltInstance namespace. |
spec.metadata.postgres.tls.caSecretRef.key | Yes* | - | Key containing the CA certificate. The Firebolt Operator mounts only this key. |
spec.metadata.replicas | No | 1 | Number of metadata service pods (only 1 is currently supported). |
spec.metadata.template | No | (Firebolt Operator default) | Pod template merged with the Firebolt Operator-rendered metadata container. See Firebolt Operator-owned fields. Image: spec.metadata.template.spec.containers[name=="metadata"].image. When imagePullPolicy is unset, the Kubernetes tag rule applies, with the mutable dev tag treated like latest. |
spec.metadata.engineRegistration | No | false | Register Engine objects in the metadata service for SQL-level RBAC. |
spec.gateway | Yes | - | Envoy gateway proxy configuration (can be empty {} for defaults) |
spec.gateway.replicas | No | 2 | Number of gateway pods. See Gateway sizing. |
spec.gateway.metricsPort | No | 9090 | Container port exposing Envoy’s Prometheus metrics endpoint. The Firebolt Operator stamps a corresponding metrics port on the container. |
spec.gateway.template | No | (Firebolt Operator default) | Pod template merged with the Firebolt Operator-rendered Envoy container. See Firebolt Operator-owned fields. Image: spec.gateway.template.spec.containers[name=="envoy"].image. When imagePullPolicy is unset, the Kubernetes tag rule applies. |
spec.auth | No | disabled | Instance-wide authentication. Applies to every Engine in the Instance; there is no per-Engine authentication. See Authentication and transport encryption. |
spec.auth.enabled | No | false | Turn authentication on. When true, spec.auth.local is required. |
spec.auth.local | Yes* | - | The local user store and the JWT parameters every Engine shares. |
spec.auth.local.admin.name | No | firebolt | Admin username. |
spec.auth.local.admin.password.name | Yes | - | Secret holding the admin password. You create it; the Firebolt Operator never generates one. |
spec.auth.local.admin.password.key | Yes | - | Key within that Secret. |
spec.auth.local.passwordLogin | No | admin_only | Who may log in by password once OIDC is configured: admin_only or any_user. Ignored when spec.auth.oidc is absent. |
spec.auth.local.signingAlgorithm | No | ES384 | JWT signing algorithm. Immutable once set, and must pair with the signing key’s algorithm and size. |
spec.auth.local.tokenExpiry | No | (Engine default) | Lifetime of issued access tokens, as a Go duration. |
spec.auth.local.maxTokenAge | No | (Engine default 1d) | Upper bound on a token’s iat age. Sets the floor for retainDuration. |
spec.auth.local.clockSkewTolerance | No | (Engine default 30s) | Permitted clock drift when validating temporal claims. Added to the retainDuration floor. |
spec.auth.local.signingKeys | No | (single permanent key) | JWT signing-key policy. cert-manager only; there is no bring-your-own path for signing keys. |
spec.auth.local.signingKeys.certManager.issuerRef.name | Yes | - | Issuer or ClusterIssuer that issues signing keys. Immutable once set. |
spec.auth.local.signingKeys.certManager.issuerRef.kind | No | ClusterIssuer | Issuer or ClusterIssuer. |
spec.auth.local.signingKeys.certManager.algorithm | No | ECDSA | ECDSA or RSA. Immutable once set. |
spec.auth.local.signingKeys.certManager.size | No | 384 | Key size. Immutable once set, and must pair with signingAlgorithm. |
spec.auth.local.signingKeys.rotationInterval | No | (no rotation) | How often to rotate the signing key, as a Go duration. Setting it opts the Instance into operator-coordinated rotation; leaving it unset keeps a single permanent key. Requires retainDuration. |
spec.auth.local.signingKeys.retainDuration | No | - | How long a demoted key keeps validating tokens, measured from confirmed post-promotion convergence. Required with rotationInterval, and must be at least maxTokenAge + clockSkewTolerance. |
spec.auth.oidc | No | - | Trusted OIDC providers whose tokens Engines accept, in addition to local login. |
spec.auth.oidc.providers[].name | Yes | - | Provider identifier, as advertised to clients. |
spec.auth.oidc.providers[].discoveryURL | Yes | - | The provider’s OIDC discovery document URL. |
spec.auth.oidc.providers[].usernameMapping | Yes | - | Template mapping token claims to a Firebolt username, e.g. {{ email }}. |
spec.auth.oidc.providers[].audience | No | (the Instance resource) | Expected aud when the provider mints its own audience rather than honouring the resource parameter. |
spec.auth.oidc.providers[].jitProvisioning | No | disabled | Create users automatically on first login. |
spec.auth.preferredAuthorizationServer | No | - | Which authorization server clients should default to: _local, or a configured provider name. Advisory to clients only. |
spec.tls | No | disabled | Transport encryption. Engine and Gateway TLS are independent and separately opt-in. |
spec.tls.engine | No | disabled | Terminates TLS on each Engine’s query listener. TLS replaces plaintext on the same port. |
spec.tls.gateway | No | disabled | Terminates client-facing TLS on the Gateway listener. |
spec.tls.*.enabled | No | false | Turn this listener’s TLS on. Engine TLS requires certManager; Gateway TLS requires exactly one of certManager or secretRef. |
spec.tls.*.certManager.issuerRef.name | Yes* | - | Issuer or ClusterIssuer that issues this certificate. |
spec.tls.*.certManager.issuerRef.kind | No | ClusterIssuer | Issuer or ClusterIssuer. |
spec.tls.*.certManager.algorithm | No | ECDSA | ECDSA or RSA. |
spec.tls.*.certManager.size | No | 384 | Key size. |
spec.tls.gateway.secretRef.name | Yes* | - | Bring-your-own Gateway certificate: a Secret carrying tls.crt and tls.key. Mutually exclusive with certManager. Engine TLS does not support secretRef. |
spec.tls.gateway.clientCASecretRef.name | No | - | Client CA to verify client certificates against, upgrading the Gateway listener to mutual TLS. Replacing it is a tightening transition and is staged fail-closed. Engine listeners do not support client-certificate verification. |
spec.tls.gateway.dnsNames | No | (in-cluster Service names) | Extra Gateway certificate SANs the Firebolt Operator cannot derive itself, such as an externally-visible hostname. Engine certificate names are derived automatically. |
Firebolt Operator-owned fields on component templates
spec.gateway.template and spec.metadata.template are full
PodTemplateSpec
embeds. The validating webhook (vfireboltinstance.compute.firebolt.io)
walks every template at admission time and rejects user input on
fields the Firebolt Operator manages end-to-end.
The same set of pod-level fields is rejected on both components:
| Pod-level field | Reason |
|---|---|
spec.template.spec.subdomain | Firebolt Operator-owned for the headless-DNS contract. |
spec.template.spec.hostname | Firebolt Operator-owned. |
spec.template.spec.restartPolicy | Fixed by the Deployment / StatefulSet controller. |
spec.template.spec.activeDeadlineSeconds | Incompatible with long-lived component pods. |
spec.template.spec.terminationGracePeriodSeconds | Firebolt Operator-stamped per component (15s gateway, 30s metadata). |
spec.template.metadata.labels[firebolt.io/*] | Reserved label prefix. |
spec.template.metadata.annotations[firebolt.io/*] | Reserved annotation prefix (most importantly firebolt.io/config-hash, which drives pod rollouts). |
| Container field | Gateway (envoy) | Metadata (metadata) |
|---|---|---|
command, args, ports, readinessProbe, livenessProbe, startupProbe | Rejected | Rejected |
lifecycle | Rejected (the Firebolt Operator owns the bash /dev/tcp preStop drain hook) | Rejected |
securityContext | Rejected (hardened defaults: non-root UID 101, drop ALL caps) | Rejected (RunAsUser pinned to the selected metadata generation’s built-in UID) |
env | Rejected | Rejected (POSTGRES_USERNAME_FILE, POSTGRES_PASSWORD_FILE, PGSSLMODE, and PGSSLROOTCERT are Firebolt Operator-injected) |
envFrom | Rejected | Rejected |
volumeMounts | Rejected (config-volume / tmp are Firebolt Operator-rendered) | Rejected (config / postgres-creds / postgres-ca / tmp are Firebolt Operator-rendered) |
image, imagePullPolicy | Allowed | Allowed |
resources | Allowed | Allowed |
- All pod-level scheduling fields:
nodeSelector,tolerations,affinity,topologySpreadConstraints,priorityClassName. - Pod-level:
securityContext(PodSecurityContext),imagePullSecrets,serviceAccountName, additionalvolumes(names that do not collide with Firebolt Operator-owned volume names). - Additional
containers(sidecars): Appended after the Firebolt Operator-rendered primary container. - Additional
initContainers: Passed through verbatim. - Sidecars and init containers may mount the Firebolt Operator-rendered
config-volume/configandtmpvolumes, but not the Secret-backed ones:tls-gateway,client-ca,engine-ca,engine-crl,client-crl, andwake-agent-tokenon the gateway;postgres-credsandpostgres-caon the metadata pod. - Pod-template
metadata.labelsandmetadata.annotationsoutside thefirebolt.io/reserved prefix.
envoy or metadata) is rejected as a duplicate.
Instance phases
| Phase | Meaning |
|---|---|
Provisioning | Components are being deployed. Not yet ready. |
Ready | Metadata service and gateway are healthy |
Degraded | Was previously Ready, but one or more components became unhealthy |
Failed | Terminal error requiring manual intervention (e.g., multiple accounts found in metadata) |
Status properties
| Field | Description |
|---|---|
status.phase | Instance lifecycle phase. See Instance phases. |
status.metadataReady | Whether the metadata service Deployment has a ready replica. |
status.gatewayReady | Whether the gateway Deployment has a ready replica. |
status.metadataEndpoint | In-cluster metadata gRPC endpoint (cleared when metadata is not ready). |
status.gatewayEndpoint | In-cluster gateway HTTP endpoint (cleared when gateway is not ready). |
status.conditions | Ready, MetadataReady, GatewayReady, AuthReady, EngineTLSReady, GatewayTLSReady, InstanceIDCanonical. See Conditions. |
status.auth | Provisioned auth material and rotation progress. Present only when spec.auth is enabled, or when a previously-enabled Instance still holds its generation counter. |
status.auth.signingKeys[] | Each tracked signing key: id, secretName, phase (Active, ValidationOnly, Removing), algorithm, size, createdAt, demotedAt, retireEligibleAt. |
status.auth.signingKeyGeneration | Monotonic counter behind each key’s id. Never decreases, so a re-enabled Instance never reuses a retired key’s identifier. |
status.auth.pendingRotationStep | The rotation step waiting for the fleet to converge: AwaitingPromotion, AwaitingRetireAnchor, or AwaitingRemoval. Empty when nothing is waiting. |
status.auth.pendingSince | When the current pending step began waiting. Preserved across reconciles, so it measures the wait rather than the last reconcile. |
status.auth.laggingEngines | Engines the pending step is waiting for, truncated for large fleets. |
status.auth.laggingEngineCount | How many engines the pending step is waiting for, including any truncated from the list above. |
status.engineTLS | Provisioned engine-listener TLS: secretName, createdAt, and reencrypting — whether the Gateway is currently re-encrypting to Engines, which tracks the whole fleet’s observed protocol rather than the certificate’s existence. |
status.gatewayTLS | Provisioned Gateway TLS: secretName, createdAt, mode (TLS or MutualTLS), and clientCAFingerprint. Cleared for the whole fail-closed window of a tightening transition, so its presence means the listener is actually serving that posture. |
status.rolledEngineTrustCAs | Fingerprints of the Engine CAs the Gateway has confirmed it trusts. A generation’s Service selector may not flip until its CA appears here. |
Conditions
| Condition | In the Ready roll-up | Meaning |
|---|---|---|
Ready | - | Roll-up of the conditions below that participate. |
MetadataReady | Yes | Metadata service (and its PostgreSQL) are usable. |
GatewayReady | Yes | Gateway has a ready replica. |
EngineTLSReady | Yes | Engine TLS is provisioned and the whole fleet re-encrypts. Convergence-gated, so Ready never advertises a secure posture the fleet has not reached. |
GatewayTLSReady | Yes | Gateway TLS is provisioned and the secure listener is serving. |
AuthReady | No | Auth material is provisioned. Deliberately excluded from the roll-up: auth provisioning has no bearing on whether the Metadata Service or Gateway are usable. Stays True with reason RotationWaitingForEngines while a signing-key rotation is parked, since the Active key still signs and validates. |
InstanceIDCanonical | No | spec.id is a lowercase Crockford ULID, or is not a Crockford ULID at all (an id you supplied, which the Firebolt Operator never rewrites). False with reason ImageBelowFloor when the id is uppercase and a resolved engine or metadata image is older than the canonicalize floor, ImageResolveFailed when a bound engine image cannot be resolved, or UpdateRejected when the case-only update is refused at admission — the Firebolt Operator leaves the field unchanged in every case, so older images keep the spelling they already run. Absent when the operator has no canonicalize floor compiled in. |
fire.