Prerequisites

A copy-pasteable checklist for standing up Definite On-Prem on a fresh cluster. Work top to bottom. definite bootstrap installs the cluster-side prerequisites for you; definite doctor verifies the external ones. This page is the manual reference behind both.

At a glance

Local tooling (on the machine running definite)

The CLI shells out to kubectl and helm; both must be on PATH.

• kubectl 1.28+ — within one minor version of the cluster's control plane. Check: kubectl version --client.
• helm 3.12+ — Helm 3 only; Helm 2 is not supported. Check: helm version.
• A kubeconfig context pointed at the target cluster, with permission to create namespaces, CRDs, and cluster-scoped RBAC. Check: kubectl config current-context and kubectl auth can-i create namespace.

Kubernetes cluster

• Kubernetes 1.28 or newer. GKE, EKS, AKS, or a conformant vanilla cluster. GKE is the primary tested target; EKS and AKS examples ship in examples/ and are actively maturing.
• Outbound network access for image pulls (ghcr.io/definite-app by default) and for the LLM provider. Air-gapped install is not supported in v1 — see network-requirements.md for data-source connectivity and architecture.md for the component map. If you mirror images into a private registry, set the image: block in your config.yaml.
• Enough headroom for the default resource requests in your chosen examples/minimal-*.yaml. The lakehouse runs as embedded DuckDB inside the API and job-runner pods (no separate query pod), so the API and job-runner are the components to size for query memory; bump resources.api / resources.jobRunner for heavy steady-state SQL, or add a compute profile for heavy bursty SQL.

Cluster prerequisites (definite bootstrap installs these)

Run definite bootstrap once against a fresh cluster, or definite bootstrap --dry-run to see what is missing first. Each item below can also be installed by hand with helm / kubectl.

• Ingress controller. Provides HTTP/S routing for the deployment's Ingress. Any current controller works (ingress-nginx, or a cloud controller such as the AWS Load Balancer Controller or GKE ingress).
• cert-manager 1.13+ and its CRDs. Required when deployment.tls is cert_manager so the ingress certificate can be issued automatically. The CRDs must be installed before cert-manager itself. definite bootstrap installs cert-manager with its leader-election lease pinned to the cert-manager namespace (--set global.leaderElection.namespace=cert-manager) — the chart default of kube-system is Google-managed on GKE Autopilot and rejects writes, so without the override the webhook CA is never injected.
• letsencrypt-prod ClusterIssuer. A healthy cert-manager still issues nothing without an Issuer. The Helm chart annotates the Ingress with cert-manager.io/cluster-issuer: letsencrypt-prod, so that issuer must exist. definite bootstrap creates it (production Let's Encrypt ACME, http01 solver) after cert-manager is up; the ACME contact email defaults to hello@definite.app and can be set with --acme-email. Use a real DNS hostname that you control. Shared convenience domains such as *.nip.io are globally rate-limited by Let's Encrypt and are rejected by definite init when deployment.tls is cert_manager.
• agent-sandbox CRDs. Custom resources the Fi runtime uses to dispatch a fresh sandbox per agent run. definite doctor probes for these and will fail preflight if they are absent.

Storage

The lakehouse itself needs no persistent volume — its catalog lives in Postgres and its data lives in the object store. PVCs are only needed when Fi is enabled (each sandbox gets an ephemeral /workspace volume).

• A StorageClass for Fi sandbox workspaces (only if fi.enabled: true). You need a StorageClass that provisions ReadWriteOnce volumes — e.g. gp3 on EKS, standard-rwo / premium-rwo on GKE, managed-csi on AKS. Set it as fi.sandbox.storage_class_name (and per-profile storage_class_name on any compute profiles).
• A sensible default StorageClass, or an explicit name in config, so PVCs bind without manual intervention. Check: kubectl get storageclass.

Postgres (customer-provided)

The application database. Definite operates no stateful database itself.

• Postgres 15 or newer. definite doctor runs SELECT version() and warns below 15.
• A dedicated database and a role that owns it. Definite manages its own schema inside that database via migrations on first boot.
• pgcrypto available. No extensions beyond pgcrypto are required.
• Reachable from inside the cluster on its port (5432 by default). A connection that works from your laptop can still fail from the cluster — see network-requirements.md. Provide the connection string as postgres.url in your config.
• Automatic backups enabled. The application database holds all durable state — users, integration credentials, automations, Fi history, data apps — and a bad migration or operator mistake with no backup is unrecoverable. Definite does not back up your Postgres for you, so the managed instance must have automatic daily backups and point-in-time recovery turned on before you deploy:
  • Cloud SQL (GKE): create the instance with --backup-start-time=HH:MM and --enable-point-in-time-recovery (transaction-log retention). On an existing instance: gcloud sql instances patch <instance> --backup-start-time=07:00 --enable-point-in-time-recovery --retained-backups-count=7.
  • RDS (EKS): the bundled Terraform (deploy/terraform/aws) and scripts/install-eks.sh already provision RDS with a 7-day backup_retention_period and a daily backup window — no extra step.
  • Azure Database for PostgreSQL (AKS): automated backups are on by default; confirm the retention period (7-35 days) and, for important deployments, enable geo-redundant backup.
  • Self-managed Postgres: schedule a daily pg_dump (or pgBackRest) to off-host storage — see backup-restore.md. Take an on-demand backup immediately before every definite upgrade; see the upgrade note in backup-restore.md.

Object store (customer-provided)

Bulk lakehouse parquet data lives here; the DuckLake catalog lives in the ducklake_catalog Postgres database (above).

• A bucket / container on S3, GCS, Azure Blob, or MinIO, dedicated to this deployment.
• Credentials with read AND write on that bucket. S3 on EKS can use IRSA (object_store.credentials.mode: irsa) so pods assume a scoped IAM role through the AWS credential chain. Static HMAC credentials remain supported for S3-compatible stores and customers that prefer them; see examples/minimal-eks.yaml.
• A prefix for Definite's objects (lakehouse.prefix) if the bucket is shared with other workloads.
• Writability confirmed. definite doctor validates object-store config shape but does not yet round-trip a real write. Confirm the credentials can PutObject into the bucket yourself before deploying.
• CORS rule for Drive. The Drive feature uploads files straight from the browser to the bucket via presigned PUT URLs, so the bucket needs a CORS policy allowing GET and PUT from the deployment's web origin (the https://… URL users open). Without it, browser uploads fail with a CORS error while the headless definite run load flow keeps working. On Azure the storage account's CORS must also allow the x-ms-blob-type header, and a private-endpoint blob account must be reachable from end-user browsers. See drive.md for the exact rules. (No effect on API access; this is browser-only.)

Optional

• OIDC provider for SSO. Local Postgres auth is the shipped fallback; OIDC (Okta, Entra) is being hardened.
• LLM credentials. Bring your own: Anthropic, Bedrock, Vertex, or Azure OpenAI. definite doctor does a real API ping for Anthropic and config-validation for the others.

Next steps

1. definite bootstrap --dry-run — confirm what the cluster is missing.
2. definite bootstrap — install the cluster prerequisites.
3. cp examples/minimal-<cloud>.yaml ./config.yaml and edit it.
4. definite doctor --config config.yaml — verify Postgres, Kubernetes, object store, and LLM.
5. definite init --config config.yaml — deploy.

See cli.md for the full command reference.