Quickstart

Create a Firebolt instance and engine with the Firebolt Operator.

This quickstart creates the minimal resources needed to run a Firebolt Engine with the Firebolt Operator.

Before you get started

You need the following tools installed on your machine:

• kind. You use this to create a local Kubernetes cluster.
• Docker. Required to run containers for kind.
• kubectl. You use this to interact with your Kubernetes cluster.
• Helm. You use this to install the Firebolt Operator.

Create a local cluster

Create a Kubernetes cluster with kind on your local machine:

kind create cluster --name firebolt

Verify the cluster is running:

kubectl get nodes

You should see a single node with Ready status:

NAME                    STATUS   ROLES           AGE   VERSION
firebolt-control-plane  Ready    control-plane   30s   v1.35.0

Install the Firebolt Operator

Install the CRDs and operator with Helm:

helm upgrade --install firebolt-crds oci://oci.firebolt.io/firebolt-db/helm-charts/firebolt-operator-crds
helm upgrade --skip-crds --install firebolt-operator oci://oci.firebolt.io/firebolt-db/helm-charts/firebolt-operator

The oci.firebolt.io host is Firebolt’s Scarf gateway. It records anonymous download statistics and redirects to GitHub Container Registry. To bypass the gateway, use oci://ghcr.io/firebolt-db/helm-charts instead.

For more installation options, see Installation.

Create a namespace

Create a namespace for the instance and engine:

kubectl create namespace firebolt

Create a FireboltInstance

A FireboltInstance provisions the metadata infrastructure that engines depend on.

apiVersion: compute.firebolt.io/v1alpha1
kind: FireboltInstance
metadata:
  name: quickstart
  namespace: firebolt
spec:
  metadata: {}
  gateway: {}

Apply the manifest:

kubectl apply --server-side -f instance.yaml

Check progress:

kubectl get fire -n firebolt

Wait until the instance is Ready before creating an engine. See the FireboltInstance CRD reference for all supported fields and phases.

Configure object storage

Every FireboltEngine requires object storage for managed tablet data. Local filesystem storage mode is not supported by the Firebolt Operator and the engine will refuse to start without object storage.

On a real cluster, point the engine at an existing bucket (S3, GCS, or Azure Blob) and grant access through your platform’s workload identity. For Amazon S3, see Amazon S3. For a local cluster (Kind, minikube), deploy a small S3-compatible emulator (floci) and create a bucket:

kubectl apply -f https://raw.githubusercontent.com/firebolt-db/firebolt-kubernetes-operator/main/examples/object-storage-local.yaml

This deploys floci into the firebolt namespace, exposes it at http://floci.firebolt.svc.cluster.local:4566, and creates a my-engine-bucket bucket. The engine references it through spec.customEngineConfig.storage in the next step.

Create a FireboltEngine

Once the instance is Ready, create an engine that references it. The customEngineConfig.storage block points the engine at the object storage configured above.

apiVersion: compute.firebolt.io/v1alpha1
kind: FireboltEngine
metadata:
  name: my-engine
  namespace: firebolt
spec:
  instanceRef: quickstart
  replicas: 1
  customEngineConfig:
    storage:
      managed_table_storage: s3
      managed_table_bucket_name: my-engine-bucket
      aws:
        endpoint: http://floci.firebolt.svc.cluster.local:4566
        path_style_addressing: true # non-AWS S3-compatible store; ignored for AWS S3
  template:
    spec:
      containers:
        - name: engine
          # floci is zero-auth, but the engine still signs S3 requests — supply any creds via env.
          env:
            - name: AWS_ACCESS_KEY_ID
              value: firebolt
            - name: AWS_SECRET_ACCESS_KEY
              value: firebolt
          resources:
            requests:
              cpu: "2"
              memory: "3Gi"
            limits:
              memory: "3Gi"

Apply the manifest:

kubectl apply --server-side -f engine.yaml

Check progress:

kubectl get fireng -n firebolt

Wait until the engine reaches stable phase with READY=True:

NAME        REPLICAS   PHASE    READY   GENERATION   AGE
my-engine   1          stable   True    0            30s

See the FireboltEngine CRD reference for the full field surface.

Run a query

Once the engine is ready, run a query through the instance gateway with the Firebolt CLI bundled in the engine image:

ENGINE_POD=$(kubectl get pod -n firebolt -l firebolt.io/engine=my-engine -o jsonpath='{.items[0].metadata.name}')
kubectl exec -n firebolt "$ENGINE_POD" -c engine -- \
  firebolt client \
    --endpoint http://quickstart-gateway \
    --insecure \
    --set engine=my-engine \
    -c "SELECT 42" \
    --no-interactive

--endpoint targets the instance gateway Service. --set engine=<name> selects the engine to route to (the same value you would pass in the X-Firebolt-Engine header). --no-interactive prints the result and exits, which suits non-TTY kubectl exec sessions.

You should see the query result in the output.

Clean up

Delete the kind cluster to free all resources:

kind delete cluster --name firebolt