> ## Documentation Index > Fetch the complete documentation index at: https://firebolt-aggregate-helm-docs-pr-97.mintlify.site/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 [Customize component pods](../instance/overview#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](#firebolt-operator-owned-fields-on-component-templates). 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](../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`. 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](../security#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`](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 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](#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](#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`.