> ## Documentation Index > Fetch the complete documentation index at: https://firebolt-aggregate-helm-docs-pr-38.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 [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`. 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](../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 | (packdb default) | Lifetime of issued access tokens, as a Go duration. | | `spec.auth.local.maxTokenAge` | No | (packdb default `1d`) | Upper bound on a token's `iat` age. Sets the floor for `retainDuration`. | | `spec.auth.local.clockSkewTolerance` | No | (packdb 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. Requires exactly one of `certManager` or `secretRef`. | | `spec.tls.*.certManager.issuerRef.name` | Yes\* | - | `Issuer` or `ClusterIssuer` that issues this certificate. Immutable while TLS stays enabled. | | `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.*.secretRef.name` | Yes\* | - | Bring-your-own certificate: a Secret carrying `tls.crt` and `tls.key`. Mutually exclusive with `certManager`. | | `spec.tls.*.clientCASecretRef.name` | No | - | Client CA to verify client certificates against. On the Gateway this upgrades the listener to mutual TLS. Replacing it is a tightening transition and is staged fail-closed. | | `spec.tls.*.dnsNames` | No | (in-cluster Service names) | Extra SANs the Firebolt Operator cannot derive itself, such as an externally-visible hostname. | \* 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`, `AuthReady`, `EngineTLSReady`, `GatewayTLSReady`. 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. | Short name: `fire`.