Install on GCP

Stand up Definite in your own GCP project: GKE, Cloud SQL Postgres, GCS, driven by gcloud and the definite CLI.

This guide walks you through an on-prem install of Definite on Google Cloud. You'll provision the infrastructure with gcloud, install the platform with the definite CLI, and tear it down cleanly when you're done. Unlike AWS, this is currently a scripted/manual provisioning path rather than a packaged Terraform module.

By default, the install uses Definite-brokered DNS and TLS. Definite provides a URL like https://<slug>.onprem.definite.app during setup, so you do not need to configure Cloud DNS or any other customer DNS before the first successful install.

End to end: about 30 to 40 minutes, most of which is GKE and Cloud SQL spinning up.

What gets created

Prerequisites

gcloud services enable \
  container.googleapis.com \
  sqladmin.googleapis.com \
  compute.googleapis.com \
  servicenetworking.googleapis.com \
  iamcredentials.googleapis.com \
  aiplatform.googleapis.com

Phase 1: Provision GCP infrastructure

The fastest path right now is to provision with gcloud directly. The shape mirrors what the AWS Terraform module produces.

Set up shared env vars first:

export PROJECT_ID="<your-project-id>"
export REGION="<your-region>"                # e.g. us-central1
export CLUSTER_NAME="<your-cluster-name>"    # e.g. definite
export SQL_INSTANCE="<your-sql-instance>"    # e.g. definite-db
export BUCKET="<your-bucket-name>"           # e.g. <project>-definite-lake
export SA_NAME="<your-sa-name>"              # e.g. definite-lakehouse

gcloud config set project "$PROJECT_ID"

1. Create a GKE cluster

Autopilot is the simplest option (Google manages nodes):

gcloud container clusters create-auto "$CLUSTER_NAME" \
  --region "$REGION" \
  --release-channel regular

If you prefer Standard mode (more control over node pools, GPU, sole-tenant nodes), use gcloud container clusters create with a --machine-type like e2-standard-4 and at least 3 nodes.

Wire up kubectl:

gcloud container clusters get-credentials "$CLUSTER_NAME" --region "$REGION"
kubectl get nodes

2. Create Cloud SQL Postgres

gcloud sql instances create "$SQL_INSTANCE" \
  --database-version=POSTGRES_15 \
  --region="$REGION" \
  --tier=db-custom-2-8192 \
  --availability-type=REGIONAL

gcloud sql databases create definite --instance="$SQL_INSTANCE"

gcloud sql users create definite \
  --instance="$SQL_INSTANCE" \
  --password="<your-postgres-password>"

Stash the connection name (used by the Cloud SQL Auth Proxy and by postgres.url):

gcloud sql instances describe "$SQL_INSTANCE" --format='value(connectionName)'

For production, give the instance a private IP in your VPC (see Private IP setup) so the cluster can reach it without going through the auth proxy. If the instance is on the same VPC as the cluster, postgres.url looks like:

postgres://definite:${POSTGRES_PASSWORD}@<private-ip>:5432/definite

3. Create a GCS bucket for the lakehouse

gcloud storage buckets create "gs://${BUCKET}" \
  --location="$REGION" \
  --uniform-bucket-level-access \
  --public-access-prevention

Versioning is recommended for production:

gcloud storage buckets update "gs://${BUCKET}" --versioning

4. Create a service account and HMAC key for the bucket

The lakehouse reads and writes GCS through DuckDB's httpfs extension. httpfs speaks the S3 interop API, not native GCS, so it needs an HMAC key pair bound to a service account that has object-admin on the bucket. Workload Identity alone is not enough.

# Create a dedicated service account for the lakehouse.
gcloud iam service-accounts create "$SA_NAME" \
  --display-name="Definite lakehouse"

SA_EMAIL="${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

# Grant it object-admin on the lakehouse bucket only (least privilege).
gcloud storage buckets add-iam-policy-binding "gs://${BUCKET}" \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/storage.objectAdmin"

# Create the HMAC pair. The key + secret print once; capture them now.
gcloud storage hmac create "$SA_EMAIL"

The output gives you accessId (the HMAC key ID) and secret (the HMAC secret). These are what you'll set as GCS_HMAC_KEY_ID and GCS_HMAC_SECRET before running definite init.

5. (If using Vertex AI for Fi) Grant Vertex access

Bind the GKE workload identity for the API pod's service account to Vertex User on the project. The simplest way is to grant roles/aiplatform.user to the node service account the cluster runs as:

NODE_SA=$(gcloud container clusters describe "$CLUSTER_NAME" \
  --region "$REGION" \
  --format='value(nodeConfig.serviceAccount)')

# `default` resolves to the Compute Engine default SA; replace if you set one.
[ "$NODE_SA" = "default" ] && \
  NODE_SA="$(gcloud projects describe "$PROJECT_ID" --format='value(projectNumber)')-compute@developer.gserviceaccount.com"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:${NODE_SA}" \
  --role="roles/aiplatform.user"

For tighter scoping, set up Workload Identity on the deployment's API service account and bind roles/aiplatform.user to that specifically.

HMAC vs Workload Identity

Phase 2: Install Definite with the definite CLI

1. Install the CLI

curl -fsSL https://storage.googleapis.com/definite-public/definite-onprem/install.sh | sh

The install script detects your OS and architecture, downloads the matching prebuilt binary from a public Google Cloud Storage bucket, verifies its SHA256 checksum, and places definite on your PATH (default: $HOME/.local/bin). Binaries are published for macOS and Linux (arm64 and x86_64), and are uploaded by the release workflow using short-lived Workload Identity Federation credentials (no long-lived keys).

To pin a version, set DEFINITE_VERSION before piping to sh:

curl -fsSL https://storage.googleapis.com/definite-public/definite-onprem/install.sh \
  | DEFINITE_VERSION=v0.0.17 sh

Verify:

definite version

2. Bootstrap cluster prerequisites

definite bootstrap installs the cluster-level pieces that definite init assumes are already present:

Run it once against the fresh cluster:

definite bootstrap

--dry-run prints what it would install without touching the cluster. The command is idempotent; safe to re-run.

3. Let definite init request Definite-brokered DNS

The ingress controller provisions a Google Cloud Network Load Balancer. Wait for it to land, then grab its external IP:

LB_IP=$(kubectl get svc ingress-nginx-controller -n ingress-nginx \
  -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
)
echo "$LB_IP"

You'll get something like 34.x.y.z.

For the default path, do not stop here to ask the customer to create DNS. definite init calls the Definite setup broker for you, using the ingress target above when brokered DNS supports that target type. The backend contract is POST /onprem/v1/setup-sessions, but users and agents should not run a direct curl by default.

definite init --config config.yaml --dns-mode definite-brokered

The CLI returns a URL like:

https://<slug>.onprem.definite.app

4. Build config.yaml

Start from the GKE example config: minimal-gke.yaml. The shape:

deployment:
  name: definite
  namespace: definite
  dns_mode: definite-brokered

broker:
  # Optional. Omit for the default GCP path: definite init uses gcloud to
  # acquire a short-lived setup token automatically.
  # setupToken:
  #   env: DEFINITE_ONPREM_SETUP_TOKEN

postgres:
  url: postgres://definite:${POSTGRES_PASSWORD}@<cloud-sql-private-ip>:5432/definite

object_store:
  type: gcs
  bucket: <your-bucket-name>
  # GCS HMAC pair from `gcloud storage hmac create`.
  credentials:
    key_id:
      env: GCS_HMAC_KEY_ID
    secret:
      env: GCS_HMAC_SECRET

lakehouse:
  prefix: lake/
  storage:
    size: 50Gi
    storage_class_name: premium-rwo  # GKE shorthand for PD-SSD

auth:
  mode: local                        # or `oidc` for SSO
  initial_admin_email: admin@<your-domain>
  initial_admin_password:
    env: INITIAL_ADMIN_PASSWORD

llm:
  provider: vertex
  project: <your-project-id>
  region: <your-region>
  # Credentials via Workload Identity on the node SA; no credentials block needed.

resources:
  api:
    replicas: 2
    cpu: "1"
    memory: 2Gi
  lakehouse:
    replicas: 1
    cpu: "4"
    memory: 16Gi
  frontend:
    replicas: 2
    cpu: 500m
    memory: 512Mi
  job_runner:
    replicas: 1
    cpu: 500m
    memory: 1Gi

For the full list of knobs (image registry overrides, ingress class, sandbox configuration, etc.), see the config reference in Definite's built-in docs, available in-product once your deployment is running.

5. Export secrets

config.yaml references env vars for every secret:

export POSTGRES_PASSWORD="<your-postgres-password>"
export GCS_HMAC_KEY_ID="<accessId-from-step-4>"
export GCS_HMAC_SECRET="<secret-from-step-4>"
export INITIAL_ADMIN_PASSWORD="$(openssl rand -base64 24 | tr -dc 'A-Za-z0-9' | head -c 24)"
export OIDC_CLIENT_SECRET=...        # only if auth.mode: oidc

Do not export LICENSE_KEY or DEFINITE_ONPREM_SETUP_TOKEN for the default brokered flow. definite init obtains the setup token and license from Definite after proving the active GCP identity.

6. (Optional) Use LiteLLM gateway

If you want a single LLM gateway in front of Vertex (for rate limiting, request logging, model routing, etc.), deploy LiteLLM into the cluster and set llm.provider: anthropic in config.yaml with api_key pointing at LiteLLM's master key. LiteLLM presents an Anthropic-shaped API while talking to Vertex behind the scenes.

7. Preflight with definite doctor

definite doctor --config config.yaml

doctor runs a battery of preflight checks: it connects to Postgres and runs SELECT version(), validates the Kubernetes context, checks object-store config shape, and (for Anthropic) pings the LLM API. Fix anything it flags before moving on.

8. Deploy with definite init

definite init --config config.yaml

init re-runs preflight, renders the bundled Helm chart with your values, and runs helm upgrade --install. It waits for pods to reach Ready by default. Useful flags:

Watch the rollout in another terminal:

definite status --config config.yaml
definite logs api --follow

9. Log in as the initial admin

For local auth, the auth.initial_admin_email and auth.initial_admin_password.env settings in config.yaml are passed into the Helm install. On first startup, the API creates the initial admin from those values; you do not need a follow-up kubectl set env rollout.

Save the generated INITIAL_ADMIN_PASSWORD somewhere safe (1Password, Vault, etc.).

When the brokered URL reports DNS/TLS ready, open https://<brokered-hostname> in a browser and log in with the admin email and password from above.

Day-2 operations

The same CLI handles upgrades, logs, license, and lakehouse maintenance. A few of the most common commands:

definite status   --config config.yaml         # `kubectl get pods,svc,ingress` for the namespace
definite logs api --follow                     # stream component logs
definite upgrade  --config config.yaml         # re-render and re-apply with the current CLI version
definite license  status                       # show the deployment's live plan + activation status
definite run maintenance stats                 # lakehouse file/snapshot stats

Definite's built-in docs include a full CLI reference for every command and flag.

Phase 3: Teardown

# Trigger Kubernetes to delete the cloud load balancer cleanly.
kubectl delete svc ingress-nginx-controller -n ingress-nginx --ignore-not-found

# Lakehouse bucket (snapshot first if you care about the data).
gcloud storage rm -r "gs://${BUCKET}"

# Service account + HMAC key.
gcloud storage hmac list --service-account="$SA_EMAIL"
gcloud storage hmac delete <accessId>
gcloud iam service-accounts delete "$SA_EMAIL"

# Postgres (take a snapshot first if you want a backup).
gcloud sql instances delete "$SQL_INSTANCE"

# GKE cluster.
gcloud container clusters delete "$CLUSTER_NAME" --region "$REGION"

For production teardowns, snapshot Cloud SQL and back up the GCS bucket first; once they're deleted, they're gone.

Troubleshooting

Next steps

• Connect a data source to start ingesting data.
• Set up the MCP server so Claude, Cursor, or Windsurf can query your deployment.
• For deeper config (custom container registry, sandbox network policies, OIDC tuning), see the config reference in Definite's built-in docs.

Support

For issues or questions, contact hello@definite.app.