FireboltInstance CRD reference

Spec reference

Pod configuration for the gateway and metadata components lives on a raw PodTemplateSpec 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, `spec.metadataNG: true` defaults to `Always`; otherwise 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`	One of	-	The provider’s OIDC discovery document URL. Sugar for `target.discoveryURL`; set this or `target`, never both.
`spec.auth.oidc.providers[].target`	One of	-	The server clients authenticate at, named apart from `exchange`. Set this or `discoveryURL`, never both.
`spec.auth.oidc.providers[].target.discoveryURL`	Yes	-	The target’s OIDC / RFC 8414 discovery document URL.
`spec.auth.oidc.providers[].target.tokenEndpointAuthMethod`	No	-	Client authentication method Engines republish to clients for the target’s token endpoint, e.g. `client_secret_post`. For providers whose discovery document omits `token_endpoint_auth_methods_supported`. Engines do not interpret it.
`spec.auth.oidc.providers[].exchange`	No	(single-hop)	RFC 8693 token-exchange server whose issuer Engines trust. Setting it makes the provider two-hop: clients exchange their target token here, and Engines accept only what this server minted.
`spec.auth.oidc.providers[].exchange.discoveryURL`	Yes	-	The exchange’s RFC 8414 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.oidc.providers[].roleMapping`	No	-	Give principals membership in existing Firebolt roles from a token claim, on every login. Closed: a claim value with no entry grants nothing. Requires an Engine build that accepts `role_mapping`.
`spec.auth.oidc.providers[].roleMapping.claim`	No	`role`	The token claim whose value is looked up in `map`.
`spec.auth.oidc.providers[].roleMapping.map[]`	Yes	-	Entries of `{value, role}`, at least one. Values must be unique; the API server rejects a repeat. The role must already exist — a mapping grants membership, never a privilege.
`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.

* Required when the parent field is set.

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).

Per-component primary container rejections:

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

Per-component pass-through (allowed without restriction):

All pod-level scheduling fields: nodeSelector, tolerations, affinity, topologySpreadConstraints, priorityClassName.
Pod-level: securityContext (PodSecurityContext), imagePullSecrets, serviceAccountName, additional volumes (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 / config and tmp volumes, but not the Secret-backed ones: tls-gateway, client-ca, engine-ca, engine-crl, client-crl, and wake-agent-token on the gateway; postgres-creds and postgres-ca on the metadata pod.
Pod-template metadata.labels and metadata.annotations outside the firebolt.io/ reserved prefix.

A second container or init container using the Firebolt Operator-rendered primary name (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.

Short name: fire.

Overview

Performance and Observability

Security

Self-Managed

Managed service

Guides

SQL reference

Release notes

API reference

Legal

Spec reference

Firebolt Operator-owned fields on component templates

Instance phases

Status properties

Conditions

​Spec reference

​Firebolt Operator-owned fields on component templates

​Instance phases

​Status properties

​Conditions

Spec reference

Firebolt Operator-owned fields on component templates

Instance phases

Status properties

Conditions