Skip to content

quickstart.mdx

Latest commit

 

History

History
137 lines (94 loc) · 5.01 KB

quickstart.mdx

File metadata and controls

137 lines (94 loc) · 5.01 KB
Raw
description 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.
sidebarTitle Quickstart
title Quickstart

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](./usage/object-storage/amazon-s3).

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.

# my-values.yaml
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