Quickstart

Install the firebolt-instance Helm chart on a local kind cluster with an in-cluster S3 emulator and run your first query through the gateway.

This page walks through a complete local install of the firebolt-instance Helm chart on kind, from an empty machine to your first query.

The walkthrough uses kind for the cluster and an in-cluster S3 emulator for engine storage, so it needs no cloud resources. For the full cluster, tooling, and storage requirements, see Prerequisites.

Before you get started

Install the following tools:

• kind to create a local Kubernetes cluster.
• Docker to run the containers that back kind.
• kubectl to interact with the cluster.
• Helm v3 to install the chart.

Create a local cluster

Create a kind cluster on your machine:

kind create cluster --name firebolt

Confirm the node is ready:

kubectl get nodes

The node reports Ready:

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

Create a namespace

Create the namespace that holds the storage emulator and the release:

kubectl create namespace firebolt

Deploy object storage

Engines store managed table data in object storage and refuse to start against a local filesystem. On a real cluster, point the engine at an S3 or S3-compatible bucket and grant access through your platform’s workload identity, as described in Amazon S3 object storage. For this local cluster, deploy the floci S3 emulator, which also creates the bucket the engine uses:

kubectl apply -n firebolt -f https://raw.githubusercontent.com/firebolt-db/firebolt-instance-helm/main/local-floci.yaml

Wait for floci and its bucket-creation job to finish:

# Wait for the floci deployment to roll out.
kubectl -n firebolt rollout status deployment/floci --timeout=120s

# Wait for the one-shot job that creates the firebolt-managed bucket.
kubectl -n firebolt wait --for=condition=complete job/floci-mkbucket --timeout=120s

floci stores data in the pod’s ephemeral filesystem and validates no credentials, so it is for local development only. Production deployments use a real object store. See Object Storage.

Configure the engine

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).

# my-values.yaml
engineSpec:
  extraEnv:
    - name: AWS_ACCESS_KEY_ID
      value: firebolt
    - name: AWS_SECRET_ACCESS_KEY
      value: firebolt

customEngineConfig:
  storage:
    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.

Install the chart

Install the chart into the firebolt namespace from its published location:

helm install firebolt oci://oci.firebolt.io/firebolt-db/helm-charts/firebolt-instance \
  --namespace firebolt \
  -f my-values.yaml

The oci.firebolt.io host is Firebolt’s Scarf gateway, which records anonymous download analytics and redirects to GHCR. To install without it, pull from oci://ghcr.io/firebolt-db/helm-charts/firebolt-instance instead.

Verify the install

List the workloads the release created:

kubectl -n firebolt get statefulset,deployment

Wait until firebolt-engine-default-node-0, firebolt-metadata-pg, firebolt-gateway, and firebolt-metadata-service all report READY. The engine pod stays NotReady until it can reach the bucket, so if it does not become ready, confirm the object-storage step finished.

Run a query

Run a query through the gateway from a temporary in-cluster pod. The X-Firebolt-Engine header selects the engine:

kubectl run query --rm -i --image=curlimages/curl --restart=Never -n firebolt -- \
  curl --silent "http://firebolt-gateway/" \
    -H "X-Firebolt-Engine: default" \
    -H "Content-Type: text/plain" \
    --data-binary "SELECT 1"

You should see the query result in the output.

Clean up

Delete the kind cluster to free all resources:

kind delete cluster --name firebolt

Next steps

• Single engine covers the default install in more detail.
• Multi-engine runs more than one engine in a release.
• Object Storage configures a real S3 or S3-compatible bucket.
• Operator upgrade path explains when to move to the Firebolt Kubernetes Operator for day-2 automation.