feat(storage)!: migrate engine storage config to schema (FB-1684) (#25)

# Description

Migrate `firebolt-instance-helm` to the **FB-1684** managed-table
storage schema
(no backward compatibility — the chart ships version-matched with the
engine):

- `helm/values-dev.yaml` — floci dev config → `managed_table_storage:
s3` +
`managed_table_bucket_name` + `aws.endpoint` (+ `path_style_addressing:
true`);
  drops `type: minio`/`api_scheme`/`bucket_name`/`minio`.
- `helm/templates/engine-statefulset.yaml` + `helm/values.yaml` — add
`engineSpec.extraEnv` / `extraEnvFrom`. The FB-1684 schema no longer
hardcodes
  credentials for S3-compatible stores, so callers inject
`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` via env (from a Secret in
production; `values-dev` sets `firebolt`/`firebolt` for zero-auth
floci).
- Docs migrate to the new schema, and a new **S3-compatible** page
documents
  Nebius and CoreWeave (`path_style_addressing` is a non-AWS setting).

## ⚠️ Breaking — version-matched with the engine

`customEngineConfig.storage` now uses the FB-1684 schema, which a
**post-FB-1684
engine** (packdb #23716) requires. Like the operator, the chart is
released
version-matched with the engine (`appVersion`), so this is the release
boundary,
not an in-place break. `make dev` needs a post-FB-1684 `:dev` image.

# Issue

FB-1684

# How Has This Been Tested?

- `helm template -f helm/values-dev.yaml` renders the new-schema
`customEngineConfig.storage` and the engine `AWS_*` env from `extraEnv`.
- `helm lint` (default + dev overlay): 0 failures.

# Other comments to the reviewer

- `path_style_addressing` applies only to a custom (non-AWS) endpoint;
it is ignored for AWS S3.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Breaking storage values affect every install at upgrade and
misconfigured env/endpoint can block engines from becoming Ready;
changes are mostly config/docs with a small, additive Helm template
surface.
> 
> **Overview**
> **Breaking release** aligned with post-FB-1684 engines:
`customEngineConfig.storage` must use `managed_table_storage`,
`managed_table_bucket_name`, and per-cloud `aws` / `gcp` / `azure`
blocks. Legacy `type`, `api_scheme`, `bucket_name`, and `minio` /
`azurite` shapes are documented as rejected at engine startup.
> 
> The chart adds **`engineSpec.extraEnv` and `engineSpec.extraEnvFrom`**
on the engine StatefulSet so S3-compatible stores get
`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` from env or Secrets
instead of chart-hardcoded creds. **`values-dev`** and the
**quickstart** move floci to the new schema plus placeholder AWS env
vars.
> 
> Documentation is rewritten across S3, GCS, and ABS guides, adds a
dedicated **S3-compatible** page (Nebius, CoreWeave,
`path_style_addressing`), updates **security** for credential injection,
and registers the new doc route in **docs.json** / **known_pages.json**.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
003d79d. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: dig-whois

docs/docs.json

@@ -17,6 +17,7 @@
                 "group": "Object Storage",
                 "pages": [
                   "usage/object-storage/amazon-s3",
+                  "usage/object-storage/s3-compatible",
                   "usage/object-storage/google-cloud-storage",
                   "usage/object-storage/azure-blob-storage"
                 ]

docs/known_pages.json

@@ -29,6 +29,8 @@
   "/usage/object-storage/azure-blob-storage/",
   "/usage/object-storage/google-cloud-storage",
   "/usage/object-storage/google-cloud-storage/",
+  "/usage/object-storage/s3-compatible",
+  "/usage/object-storage/s3-compatible/",
   "/usage/single-engine",
   "/usage/single-engine/"
 ]

docs/quickstart.mdx

@@ -70,17 +70,24 @@ floci stores data in the pod's ephemeral filesystem and validates no credentials
 
 ## Configure the engine
 
-Create a values file that points the engine's storage at the floci endpoint. The `type: minio` mode signs requests for an S3-compatible endpoint, and `bucket_name` matches the bucket floci created.
+Create a values file that points the engine's storage at the floci endpoint. `managed_table_storage: s3` with `aws.endpoint` targets floci, and `managed_table_bucket_name` matches the bucket floci created. floci is zero-auth, so any AWS credentials work (set via `engineSpec.extraEnv`).
 
 ```yaml
 # my-values.yaml
+engineSpec:
+  extraEnv:
+    - name: AWS_ACCESS_KEY_ID
+      value: firebolt
+    - name: AWS_SECRET_ACCESS_KEY
+      value: firebolt
+
 customEngineConfig:
   storage:
-    type: minio
-    api_scheme: "s3://"
-    bucket_name: firebolt-managed
-    minio:
+    managed_table_storage: s3
+    managed_table_bucket_name: firebolt-managed
+    aws:
       endpoint: http://floci.firebolt.svc.cluster.local:4566
+      path_style_addressing: true # non-AWS S3-compatible store; ignored for AWS S3
 ```
 
 This is the only value the local install needs. The chart's defaults provide one engine named `default`, the Envoy gateway, the Metadata Service, and a bundled PostgreSQL.

docs/security.mdx

@@ -101,7 +101,7 @@ Object-storage credentials for engines are not represented as Helm values. The c
 - Azure: [Microsoft Entra Workload ID](./usage/object-storage/azure-blob-storage#grant-the-engine-an-azure-identity).
 - Google Cloud: [Workload Identity Federation for GKE](./usage/object-storage/google-cloud-storage#grant-the-engine-a-google-identity).
 
-The chart never sees those cloud provider credentials. For S3-compatible endpoints that use the `minio` storage type, the endpoint must accept the credentials expected by the engine mode documented in [Amazon S3](./usage/object-storage/amazon-s3#use-an-s3-compatible-endpoint).
+The chart never sees those cloud provider credentials. For an S3-compatible endpoint (`managed_table_storage: s3` with `aws.endpoint`), the engine authenticates with the `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` you inject via `engineSpec.extraEnv` (from a Secret in production); see [S3-compatible storage](./usage/object-storage/s3-compatible).
 
 ### TLS to PostgreSQL is not exposed
 

docs/usage/object-storage/amazon-s3.mdx

@@ -4,13 +4,17 @@ sidebarTitle: Amazon S3
 title: Amazon S3
 ---
 
+<Warning>
+  **Breaking change.** Managed-table storage now uses `managed_table_storage` and `managed_table_bucket_name` with a per-cloud `storage.aws` / `gcp` / `azure` block. The former keys — `type`, `api_scheme`, `bucket_name`, and the `minio` / `azurite` types — are removed and are rejected by the engine at startup. This schema requires a recent engine image; keep the chart and engine on matching versions.
+</Warning>
+
 This page configures Amazon S3 or an S3-compatible endpoint as engine object storage.
 
 Every engine needs object storage for managed table data. The chart does not support local-filesystem storage for engines, so an engine pod never becomes Ready until `customEngineConfig.storage` points at object storage.
 
 With object storage as the backing store, durability does not depend on the per-pod data volumes mounted to each engine. Even a complete loss of those volumes does not cause data loss, because the authoritative copy of managed table data lives in the object store.
 
-You configure object storage on the engine through `customEngineConfig.storage`, which the chart passes through unchanged into the engine's `config.yaml`. The `type`, `api_scheme`, and `bucket_name` keys match the Firebolt Core configuration schema, and the chart does not validate them. The engine reads AWS credentials from the pod's workload identity, which you configure through [AWS IRSA](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) or [AWS Pod Identity](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html).
+You configure object storage on the engine through `customEngineConfig.storage`, which the chart passes through unchanged into the engine's `config.yaml`. The `managed_table_storage` and `managed_table_bucket_name` keys match the Firebolt Core configuration schema, and the chart does not validate them. The engine reads AWS credentials from the pod's workload identity, which you configure through [AWS IRSA](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) or [AWS Pod Identity](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html).
 
 ## Prerequisites
 
@@ -98,9 +102,8 @@ engineSpec:
 
 customEngineConfig:
   storage:
-    type: s3
-    api_scheme: "s3://"
-    bucket_name: firebolt-managed
+    managed_table_storage: s3
+    managed_table_bucket_name: firebolt-managed
 ```
 
 Create the ServiceAccount, then install the chart with the matching values:
@@ -115,15 +118,15 @@ helm install firebolt ./helm \
   -f my-values.yaml
 ```
 
-To set the AWS region explicitly, add `region` to the storage block. The EKS identity webhook usually injects the region automatically.
+To set the AWS region explicitly, add `region` under `aws`. The EKS identity webhook usually injects the region automatically.
 
 ```yaml
 customEngineConfig:
   storage:
-    type: s3
-    api_scheme: "s3://"
-    bucket_name: firebolt-managed
-    region: us-east-1
+    managed_table_storage: s3
+    managed_table_bucket_name: firebolt-managed
+    aws:
+      region: us-east-1
 ```
 
 ### Confirm that object storage works
@@ -150,16 +153,16 @@ New prefixes appear under the bucket as the engine writes data.
 
 ## Use an S3-compatible endpoint
 
-For any S3-compatible endpoint reachable from the engine pods, such as self-hosted MinIO, Ceph RGW, or an in-cluster S3 emulator, use `type: minio`. The engine signs requests with the access key and secret key `firebolt` in this mode, so the endpoint must accept those credentials.
+For any S3-compatible endpoint reachable from the engine pods, such as self-hosted MinIO, Ceph RGW, or a managed store like Nebius or CoreWeave, set `managed_table_storage: s3` and point `aws.endpoint` at the store. Supply credentials through the engine environment (`engineSpec.extraEnv` / `extraEnvFrom`); a zero-auth emulator accepts any values. See [S3-compatible storage](./s3-compatible) for Nebius and CoreWeave.
 
 ```yaml
 customEngineConfig:
   storage:
-    type: minio
-    api_scheme: "s3://"
-    bucket_name: firebolt-managed
-    minio:
+    managed_table_storage: s3
+    managed_table_bucket_name: firebolt-managed
+    aws:
       endpoint: http://minio.minio.svc.cluster.local:9000
+      path_style_addressing: true # non-AWS S3-compatible store; ignored for AWS S3
 ```
 
 `endpoint` must be a URL the engine pod can resolve and reach. Create the bucket out of band before the engine starts.
@@ -179,14 +182,13 @@ Set the intermediary role ARN under `customEngineConfig.storage.aws.intermediary
 ```yaml
 customEngineConfig:
   storage:
-    type: s3
-    api_scheme: "s3://"
-    bucket_name: firebolt-managed
+    managed_table_storage: s3
+    managed_table_bucket_name: firebolt-managed
     aws:
       intermediary_access_role: arn:aws:iam::<account-id>:role/firebolt-intermediary
 ```
 
-The chart passes the `storage.aws` block through unchanged. The block is valid only when `type` is `s3`.
+The chart passes the `storage.aws` block through unchanged. The block is valid only when `managed_table_storage` is `s3`.
 
 ## Storage scope
 

docs/usage/object-storage/azure-blob-storage.mdx

@@ -10,10 +10,10 @@ Every engine needs object storage for managed table data. The chart does not sup
 
 With Azure Blob Storage as the backing store, durability does not depend on the per-pod data volumes mounted to each engine. Even a complete loss of those volumes does not cause data loss, because the authoritative copy of managed table data lives in object storage.
 
-You configure object storage on the engine through `customEngineConfig.storage`, which the chart passes through unchanged into the engine's `config.yaml`. The `type`, `api_scheme`, and `bucket_name` keys match the Firebolt Core configuration schema, and the chart does not validate them. The engine reads Azure credentials from the pod's Azure identity, which you provide with [Microsoft Entra Workload ID](https://learn.microsoft.com/en-us/azure/aks/workload-identity-overview).
+You configure object storage on the engine through `customEngineConfig.storage`, which the chart passes through unchanged into the engine's `config.yaml`. The `managed_table_storage` and `managed_table_bucket_name` keys match the Firebolt Core configuration schema, and the chart does not validate them. The engine reads Azure credentials from the pod's Azure identity, which you provide with [Microsoft Entra Workload ID](https://learn.microsoft.com/en-us/azure/aks/workload-identity-overview).
 
 <Note>
-The chart passes `customEngineConfig.storage` through unchanged and does not validate the `type`. The `abs` backend requires an engine image that supports it. An unsupported `type` is written verbatim into the engine `config.yaml`, so the engine fails at startup rather than at install time.
+The chart passes `customEngineConfig.storage` through unchanged and does not validate `managed_table_storage`. The `abs` backend requires an engine image that supports it. An unsupported value is written verbatim into the engine `config.yaml`, so the engine fails at startup rather than at install time.
 </Note>
 
 ## Prerequisites
@@ -117,7 +117,7 @@ metadata:
 
 ### Point the chart at the container
 
-Run the engine pods under the annotated ServiceAccount, label them so Workload ID injects credentials, and set the storage block to the container. The default scheme for `abs` is `azure://`, `bucket_name` is the container name, and `azure.storage_account_name` is the storage account that holds it.
+Run the engine pods under the annotated ServiceAccount, label them so Workload ID injects credentials, and set the storage block to the container. `managed_table_bucket_name` is the container name, and `azure.storage_account_name` is the storage account that holds it.
 
 ```yaml
 # my-values.yaml
@@ -132,9 +132,8 @@ engines:
 
 customEngineConfig:
   storage:
-    type: abs
-    api_scheme: "azure://"
-    bucket_name: firebolt-managed
+    managed_table_storage: abs
+    managed_table_bucket_name: firebolt-managed
     azure:
       storage_account_name: fireboltenginedemo
 ```
@@ -192,15 +191,14 @@ Set its application client ID under `customEngineConfig.storage.azure.intermedia
 ```yaml
 customEngineConfig:
   storage:
-    type: abs
-    api_scheme: "azure://"
-    bucket_name: firebolt-managed
+    managed_table_storage: abs
+    managed_table_bucket_name: firebolt-managed
     azure:
       storage_account_name: fireboltenginedemo
       intermediary_service_principal_client_id: 35f11db5-082b-46e8-9f2f-5466d8630003
 ```
 
-The chart passes the `storage.azure` block through unchanged. The block is valid when `type` is `abs` or `azurite`.
+The chart passes the `storage.azure` block through unchanged. The block is valid when `managed_table_storage` is `abs`.
 
 ## Storage scope
 

docs/usage/object-storage/google-cloud-storage.mdx

@@ -10,10 +10,10 @@ Every engine needs object storage for managed table data. The chart does not sup
 
 With Google Cloud Storage as the backing store, durability does not depend on the per-pod data volumes mounted to each engine. Even a complete loss of those volumes does not cause data loss, because the authoritative copy of managed table data lives in the bucket.
 
-You configure object storage on the engine through `customEngineConfig.storage`, which the chart passes through unchanged into the engine's `config.yaml`. The `type`, `api_scheme`, and `bucket_name` keys match the Firebolt Core configuration schema, and the chart does not validate them. The engine reads Google Cloud credentials from the pod's Google identity, which you provide with [Workload Identity Federation for GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity).
+You configure object storage on the engine through `customEngineConfig.storage`, which the chart passes through unchanged into the engine's `config.yaml`. The `managed_table_storage` and `managed_table_bucket_name` keys match the Firebolt Core configuration schema, and the chart does not validate them. The engine reads Google Cloud credentials from the pod's Google identity, which you provide with [Workload Identity Federation for GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity).
 
 <Note>
-The chart passes `customEngineConfig.storage` through unchanged and does not validate the `type`. The `gcs` backend requires an engine image that supports it. An unsupported `type` is written verbatim into the engine `config.yaml`, so the engine fails at startup rather than at install time.
+The chart passes `customEngineConfig.storage` through unchanged and does not validate `managed_table_storage`. The `gcs` backend requires an engine image that supports it. An unsupported value is written verbatim into the engine `config.yaml`, so the engine fails at startup rather than at install time.
 </Note>
 
 ## Prerequisites
@@ -99,9 +99,8 @@ engineSpec:
 
 customEngineConfig:
   storage:
-    type: gcs
-    api_scheme: "gs://"
-    bucket_name: firebolt-managed
+    managed_table_storage: gcs
+    managed_table_bucket_name: firebolt-managed
 ```
 
 Create the ServiceAccount, then install the chart with the matching values:
@@ -153,14 +152,13 @@ Set its ID under `customEngineConfig.storage.gcp.intermediary_service_account_id
 ```yaml
 customEngineConfig:
   storage:
-    type: gcs
-    api_scheme: "gs://"
-    bucket_name: firebolt-managed
+    managed_table_storage: gcs
+    managed_table_bucket_name: firebolt-managed
     gcp:
       intermediary_service_account_id: projects/my-project/serviceAccounts/firebolt-intermediary@my-project.iam.gserviceaccount.com
 ```
 
-The chart passes the `storage.gcp` block through unchanged. The block is valid only when `type` is `gcs`.
+The chart passes the `storage.gcp` block through unchanged. The block is valid only when `managed_table_storage` is `gcs`.
 
 ## Storage scope
 

docs/usage/object-storage/s3-compatible.mdx

@@ -0,0 +1,75 @@
+---
+title: S3-compatible storage
+description: Back Firebolt engines with a non-AWS S3-compatible object store (Nebius, CoreWeave, MinIO) using firebolt-instance-helm.
+sidebarTitle: S3-compatible
+---
+
+<Warning>
+  **Breaking change.** Managed-table storage now uses `managed_table_storage` and `managed_table_bucket_name` with a per-cloud `storage.aws` / `gcp` / `azure` block. The former keys — `type`, `api_scheme`, `bucket_name`, and the `minio` / `azurite` types — are removed and are rejected by the engine at startup. This schema requires a recent engine image; keep the chart and engine on matching versions.
+</Warning>
+
+Besides Amazon S3, the engine can use any **S3-compatible** object store — for example [Nebius](https://nebius.com/) Object Storage, [CoreWeave](https://www.coreweave.com/) Object Storage, or a self-hosted [MinIO](https://min.io/). You point the engine at the store's endpoint and supply credentials through the engine container environment.
+
+## How it differs from Amazon S3
+
+For [Amazon S3](./amazon-s3) you set only `managed_table_storage` and `managed_table_bucket_name`, and credentials come from the pod's AWS identity (IRSA / Pod Identity). For an S3-compatible store you additionally set, under `storage.aws`:
+
+- `endpoint` — the store's S3 API endpoint (`https://…`).
+- `path_style_addressing` — the addressing style. **This applies only to a custom (non-AWS) endpoint; it is ignored for Amazon S3.**
+  - `true` (path-style, `endpoint/bucket/key`) — the default. Used by MinIO and Nebius.
+  - `false` (virtual-hosted, `bucket.endpoint/key`) — required by providers that support virtual-hosted addressing only, such as CoreWeave.
+- `verify_ssl` — set to `false` only for a store with a self-signed certificate or plain HTTP.
+
+Credentials are read from the AWS SDK environment chain. Inject `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` into the engine container with `engineSpec.extraEnv` (or `engineSpec.extraEnvFrom` to pull them from a `Secret`).
+
+## Nebius Object Storage
+
+Nebius exposes an S3 API at `https://storage.<region>.nebius.cloud` and supports path-style addressing (the default).
+
+Create a `Secret` from a Nebius static access key:
+
+```bash
+kubectl -n firebolt create secret generic nebius-s3-credentials \
+  --from-literal=AWS_ACCESS_KEY_ID=<nebius-access-key-id> \
+  --from-literal=AWS_SECRET_ACCESS_KEY=<nebius-secret>
+```
+
+```yaml
+# my-values.yaml
+engineSpec:
+  extraEnvFrom:
+    - secretRef:
+        name: nebius-s3-credentials
+
+customEngineConfig:
+  storage:
+    managed_table_storage: s3
+    managed_table_bucket_name: my-firebolt-bucket
+    aws:
+      endpoint: https://storage.us-central1.nebius.cloud
+      path_style_addressing: true # non-AWS S3-compatible store; ignored for AWS S3
+```
+
+## CoreWeave Object Storage
+
+CoreWeave Object Storage supports virtual-hosted addressing only, so set `path_style_addressing: false`. Use the endpoint for your CoreWeave Object Storage account, and create a `Secret` (`coreweave-s3-credentials`) the same way.
+
+```yaml
+# my-values.yaml
+engineSpec:
+  extraEnvFrom:
+    - secretRef:
+        name: coreweave-s3-credentials
+
+customEngineConfig:
+  storage:
+    managed_table_storage: s3
+    managed_table_bucket_name: my-firebolt-bucket
+    aws:
+      endpoint: https://<coreweave-object-storage-endpoint>
+      path_style_addressing: false # CoreWeave supports virtual-hosted addressing only
+```
+
+## Confirm that object storage works
+
+Install the chart with your values, wait for the engine to become `Ready`, then create a table and insert a row (see the [Quickstart](../../quickstart) for connecting to the engine). New object-storage prefixes appear under your bucket as the engine writes data — list them with your provider's CLI (`aws s3 ls s3://my-firebolt-bucket --endpoint-url <endpoint>`).

helm/templates/engine-statefulset.yaml

@@ -124,6 +124,13 @@ spec:
             # startup.
             - name: FIREBOLT_CORE_MODE
               value: "1"
+            {{- with $.Values.engineSpec.extraEnv }}
+            {{- toYaml . | nindent 12 }}
+            {{- end }}
+          {{- with $.Values.engineSpec.extraEnvFrom }}
+          envFrom:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
           command: ["/bin/bash", "-c"]
           tty: true
           stdin: true