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 Instance reconciliation.
| Field | Required | Default | Description |
|---|---|---|---|
spec.id | No | (auto-generated ULID) | Stable unique identifier for the instance, used as the metadata account ID. Immutable once set. |
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.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. |
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. |
spec.auth | No | disabled | Authentication configuration. Not enforced yet. Reserved for future engine-level auth. |
spec.auth.mode | Yes* | - | disabled, native, or openid |
spec.auth.oidc | Yes* | - | OIDC config (required when mode is openid) |
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 image’s dedicated-pensieve UID) |
env | Rejected | Rejected (POSTGRES_USERNAME_FILE / POSTGRES_PASSWORD_FILE are Firebolt Operator-injected) |
envFrom | Rejected | Rejected |
volumeMounts | Rejected (config-volume / tmp are Firebolt Operator-rendered) | Rejected (config / postgres-creds / 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. - Pod-template
metadata.labelsandmetadata.annotationsoutside thefirebolt.io/reserved prefix.
envoy, metadata) is rejected as a duplicate. The
authoritative rule sets live in
api/v1alpha1/operatorauthority.go
as GatewayPodTemplateRules and MetadataPodTemplateRules.
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. |
fire.