> ## Documentation Index > Fetch the complete documentation index at: https://docs.firebolt.io/llms.txt > Use this file to discover all available pages before exploring further. # FireboltInstance CRD reference > Spec, status, and conditions for the FireboltInstance custom resource. ## Spec reference Pod configuration for the gateway and metadata components lives on a raw [`PodTemplateSpec`](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-template-v1/) 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](#firebolt-operator-owned-fields-on-component-templates) and [Instance reconciliation](../instance/instance-reconciliation#component-pod-templates). | 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](#firebolt-operator-owned-fields-on-component-templates). 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](../instance/gateway/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](#firebolt-operator-owned-fields-on-component-templates). 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`) | \* Required when the parent field is set. ## Firebolt Operator-owned fields on component templates `spec.gateway.template` and `spec.metadata.template` are full [`PodTemplateSpec`](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-template-v1/) 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 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** | 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. * Pod-template `metadata.labels` and `metadata.annotations` outside the `firebolt.io/` reserved prefix. A second container or initContainer using the Firebolt Operator-rendered primary name (`envoy`, `metadata`) is rejected as a duplicate. The authoritative rule sets live in [`api/v1alpha1/operatorauthority.go`](https://github.com/firebolt-db/firebolt-kubernetes-operator/blob/main/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](#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`. | Short name: `fire`.