firebolt-kubernetes-operator

Firebolt Kubernetes Operator

A Kubernetes operator that manages Firebolt infrastructure: metadata services, an Envoy query-routing proxy, and compute engines with zero-downtime scaling via blue-green deployments.

Overview

The operator manages three custom resources:

• FireboltInstance provisions the shared infrastructure that engines depend on: PostgreSQL, the metadata service, and an Envoy gateway proxy.
• FireboltEngine deploys stateful compute nodes. Each engine references a FireboltInstance and cannot operate without one.
• FireboltEngineClass (optional, namespaced) holds a reusable pod-template fragment that multiple engines in the same namespace can share via spec.engineClassRef — service account / IAM binding, scheduling, sidecars, and the engine container image. Namespaced (not cluster-scoped) because the template carries namespace-resolved identifiers like ServiceAccount names and Secret/PVC volume references.

When you change an engine's configuration (e.g., scale from 3 to 5 nodes), the operator performs a zero-downtime blue-green transition: it creates a new generation, waits for readiness, switches traffic, drains the old generation, and deletes it. Editing the referenced FireboltEngineClass triggers the same blue-green flow on every consumer engine.

Documentation

For more detailed information checkout our official documentation

kubectl firebolt plugin

For convenient management there's kubectl-firebolt, a kubectl plugin that creates, lists, deletes, and port-forwards FireboltEngines and FireboltInstances without hand-authoring manifests:

make kubectl-firebolt    # builds bin/kubectl-firebolt; put it on PATH
kubectl firebolt engine create my-engine -n my-ns --instance my-instance --type my-engine-class
kubectl firebolt engine list -o wide

It builds the CRs from this repo's api/v1alpha1 types, so it versions in lockstep with the CRDs. See cmd/kubectl-firebolt/README.md for install, the full command set, and output formats.

Use this with a coding agent

Paste the following prompt into your favorite coding agent and let it drive the whole local install for you. Ours is Claude Code.

Install the Firebolt Kubernetes Operator on a local Kind cluster, then bring up a working FireboltInstance and FireboltEngine end to end.

If I only gave you the GitHub repo URL, clone the repo first. If I already opened the repo locally, work from the existing checkout.

Follow the "Quick start" section of README.md — it covers the prerequisites, the local Kind setup, object storage, and creating the FireboltInstance and FireboltEngine. Treat this as a request to actually deploy and verify the operator, not just inspect the codebase. Don't assume I have the prerequisites done; if a required tool is missing or a step is ambiguous, tell me and stop rather than guessing.

Workflow:
- Run a non-mutating discovery step first: print tool versions, Docker daemon status, any existing Kind clusters, and the current kube-context. Fail fast with a clear message if a required tool is missing or Docker is down.
- Before making any cluster changes, show me the resolved plan: which Kind cluster and registry you will create or reuse, which make targets you will run, and which namespaces and manifests you will apply.
- Prefer the repo's existing make targets and example manifests over hand-rolled kubectl/helm commands. Run make prepare-test-e2e (cluster + registry + images), then make local-deploy (build, load, Helm install). Stream the output and stop on the first error.
- Create the FireboltInstance, wait until it reports Ready, then deploy object storage and create the FireboltEngineClass + FireboltEngine. Poll for readiness with short loops; never sleep blindly.
- After everything is up, run a smoke check: confirm the operator deployment is Available and the instance and engine are Ready (kubectl get fire -n firebolt). Optionally send a trivial SQL query through the instance gateway as described in "Connecting to engines".
- When done, report the kube-context, what was deployed and where, the in-cluster gateway endpoint, and any remaining manual steps or warnings. If anything failed, show the failing command output and your best diagnosis before continuing.

This is the fast path if you want the agent to drive the install for you. If you would rather run the steps yourself, skip to the Quick start below.

Quick start

For a step-by-step walkthrough, follow the quickstart guide in our official documentation or using the documentation source file at docs/quickstart.mdx.

Firebolt Operator flags

The Firebolt Operator supports these runtime flags. The binary default is what the manager uses when you run it directly. The Helm chart default is what the firebolt-operator chart passes with its default values.yaml.

Running tests

make lint               # golangci-lint
make test               # unit tests (envtest, no cluster required)
make test-e2e           # E2E tests (requires Kind cluster)

Where to go next

• For contributor detail, conventions, and rules for making changes to this repo, see AGENTS.md.
• The Helm chart for the operator lives in helm/firebolt-operator.
• The pure CRD chart for the operator lives in helm/firebolt-operator-crds.