Install on AWS - Definite

This guide walks you through a production-grade on-prem install of Definite on AWS. You’ll provision the infrastructure with Terraform, install the platform with the definite CLI, and tear it down cleanly when you’re done. 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 Route 53 or any other customer DNS before the first successful install. End to end: about 30 to 40 minutes, most of which is terraform apply waiting on EKS and RDS.

What gets created

Resource	Notes
VPC	Private subnets for nodes and the database, public subnets for NAT and load balancers
EKS cluster	Kubernetes 1.30 (configurable), managed node group, OIDC provider enabled for IRSA
RDS Postgres 15	Private (not publicly accessible), reachable only from the cluster security group
S3 bucket	Lakehouse data; public access blocked, encryption and versioning on
IAM IRSA roles	Least-privilege roles for the lakehouse and for Fi’s Bedrock access
IAM user + access key	Static-credential fallback for the lakehouse (see IRSA vs access key)
`gp3` StorageClass	Cluster-default StorageClass the lakehouse PVC needs

Every name, instance size, CIDR, and count is a Terraform variable with a sane default. Override only what you need to in terraform.tfvars.

Prerequisites

AWS account access

AWS credentials in your shell with permission to create VPC, EKS, RDS, S3, and IAM resources. The Terraform provider reads the standard AWS credential chain (env vars, shared config, SSO, instance profile). No secrets live in the Terraform code.

Local tooling

Install the following on the machine you’ll run terraform and definite from:

Tool	Version	Check
`terraform`	1.5+	`terraform version`
`aws` CLI	recent	`aws --version`
`kubectl`	1.28+	`kubectl version --client`
`helm`	3.12+	`helm version`

LLM access

Decide which LLM provider Fi will use. Bedrock is the most common choice for AWS deployments; this guide uses it as the default. Anthropic, Vertex, and Azure OpenAI are also supported. If you go with Bedrock, make sure you’ve requested model access for Claude in the target region.

Definite broker access

In the default brokered flow, you do not need a manual Definite setup token or license key. definite init uses your active AWS credentials to create a short-lived, signed STS GetCallerIdentity proof, exchanges that proof with Definite for a setup token, then receives the brokered DNS name and license. If your organization requires a manual/customer-owned mode, contact hello@definite.app.

(Optional) Remote Terraform state

For team use, configure an S3 backend in versions.tf before applying. A backend stub is committed in the module. Single-operator installs can skip this and use local state.

Phase 1: Provision AWS infrastructure with Terraform

Download the AWS Terraform module from the public release bucket and unpack it:

curl -fsSL https://storage.googleapis.com/definite-public/definite-onprem/latest/terraform-aws.tar.gz -o terraform-aws.tar.gz
curl -fsSL https://storage.googleapis.com/definite-public/definite-onprem/latest/terraform-aws.tar.gz.sha256 | shasum -a 256 -c -
tar -xzf terraform-aws.tar.gz
cd definite-aws-terraform

To pin a specific release, replace latest with a version tag (for example v0.0.11).

1. Configure inputs

Copy the example tfvars file and edit it:

cp terraform.tfvars.example terraform.tfvars
$EDITOR terraform.tfvars

A minimal terraform.tfvars is just two lines:

region      = "<your-region>"
name_prefix = "<your-name-prefix>"

Everything else has a default. Common overrides:

# Lock the EKS public API endpoint to your office or VPN CIDRs.
cluster_endpoint_public_access_cidrs = ["<your-cidr>/24"]

# Production hardening.
rds_multi_az            = true
rds_deletion_protection = true

# Bedrock model access (must be enabled in the AWS console first).
bedrock_model_ids = ["anthropic.claude-sonnet-4-20250514-v1:0"]

See the README.md included in the module for the full list of variables.

2. Init, plan, apply

terraform init
terraform plan
terraform apply

terraform apply takes 20 to 25 minutes (mostly EKS and RDS). When it finishes, every value you need is in terraform output.

3. Read the outputs

Inspect the non-sensitive outputs:

terraform output

For sensitive values, read them explicitly with -raw:

terraform output -raw rds_password
terraform output -raw lakehouse_s3_secret_access_key
terraform output -raw postgres_url

The values you’ll feed into config.yaml are summarized here:

Terraform output	Goes into
`cluster_name`	`aws eks update-kubeconfig --name ...`
`region`	`object_store.region`, `llm.region`
`postgres_url` (sensitive)	`postgres.url`
`rds_password` (sensitive)	`POSTGRES_PASSWORD` env var
`lakehouse_bucket_name`	`object_store.bucket`
`lakehouse_prefix`	`lakehouse.prefix`
`lakehouse_s3_access_key_id`	`S3_ACCESS_KEY_ID` env var
`lakehouse_s3_secret_access_key` (sensitive)	`S3_SECRET_ACCESS_KEY` env var
`bedrock_irsa_role_arn`	Post-install `kubectl annotate` on the `definite` ServiceAccount (see Bedrock IRSA)

The module also emits a ready-to-paste, non-secret config.yaml snippet:

terraform output -raw config_yaml_fragment

IRSA vs access key

The module emits both an IRSA role and an IAM user + access key for lakehouse S3 access. Both share one identical least-privilege policy.

Option	When to use
Access key (`lakehouse_s3_access_key_id`, `lakehouse_s3_secret_access_key`)	Use this today. The lakehouse reads S3 through DuckDB’s `httpfs` extension, which speaks the S3 API with static credentials, not the AWS SDK, so it can’t assume an IRSA role yet.
IRSA role (`lakehouse_irsa_role_arn`)	The end state. Once the lakehouse gains SDK-based S3 support, annotate the ServiceAccount with this role’s ARN and delete the IAM user. No infra change needed.

Fi’s Bedrock access uses IRSA today (no static credentials).

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.11 sh

Verify:

definite version

2. Point `kubectl` at the new cluster

aws eks update-kubeconfig \
  --region "$(terraform output -raw region)" \
  --name   "$(terraform output -raw cluster_name)"

kubectl get nodes

You should see your managed node group’s nodes in the Ready state.

3. Bootstrap cluster prerequisites

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

Prerequisite	What it provides
Ingress controller	HTTP/S routing for the deployment’s `Ingress` resource
Definite-brokered DNS/TLS readiness	The default setup path uses the Definite setup broker and the returned `*.onprem.definite.app` URL
agent-sandbox CRDs	Custom resources the Fi runtime uses to dispatch per-run sandboxes

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.

4. Let `definite init` request Definite-brokered DNS

The ingress controller provisions an AWS Network Load Balancer. Wait for it to land, then grab its hostname:

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

You’ll get something like <random-id>.elb.<your-region>.amazonaws.com. For the default path, do not stop here to ask the customer to create a CNAME. definite init calls the Definite setup broker for you, using the ingress target above. 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

Customer-owned DNS is supported as an advanced/custom production option after the system is healthy. If the customer explicitly selected that mode, create a Route 53 or external CNAME from the customer hostname to $LB_HOST and use the released CLI’s customer-owned mode. The expected flag shape is --dns-mode customer-owned --hostname <hostname>. Private/internal production deployments may also need a customer certificate or private CA. Do not use nip.io, cert-manager, or Let’s Encrypt as the default first-run path.

5. Build `config.yaml`

Start from the EKS example config: minimal-eks.yaml. The shape:

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

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

postgres:
  url: postgres://<rds-user>:${POSTGRES_PASSWORD}@<rds-endpoint>:5432/<db-name>

object_store:
  type: s3
  bucket: <bucket-name>              # terraform output lakehouse_bucket_name
  region: <your-region>              # terraform output region
  credentials:
    key_id:
      env: S3_ACCESS_KEY_ID
    secret:
      env: S3_SECRET_ACCESS_KEY

lakehouse:
  prefix: lake/                      # terraform output lakehouse_prefix
  storage:
    size: 50Gi
    storage_class_name: gp3

auth:
  mode: oidc                         # or `local` for username/password auth
  issuer: https://<your-okta-domain>
  client_id: definite-onprem
  client_secret:
    env: OIDC_CLIENT_SECRET

llm:
  provider: bedrock
  region: <your-region>
  model: anthropic.claude-sonnet-4-20250514-v1:0
  # Credentials via IRSA; 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

The fastest way to fill in postgres.url, object_store.bucket, and friends is to paste the output of terraform output -raw config_yaml_fragment directly into your config.yaml.

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.

6. Export secrets

config.yaml references env vars for every secret. Export them from Terraform outputs:

export POSTGRES_PASSWORD=$(terraform output -raw rds_password)
export S3_ACCESS_KEY_ID=$(terraform output -raw lakehouse_s3_access_key_id)
export S3_SECRET_ACCESS_KEY=$(terraform output -raw lakehouse_s3_secret_access_key)
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 control of the active AWS credentials.

Don’t commit config.yaml, terraform.tfvars, or terraform.tfstate to a public repo. The state file holds the RDS password and the S3 secret in cleartext.

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:

Flag	Purpose
`--dry-run`	Render values, don’t apply
`--wait=false`	Return as soon as Helm finishes; don’t wait for pods
`--skip-preflight`	Skip `doctor`. Use only when the per-cloud troubleshooting path says a private-network check is expected to fail from your laptop

Watch the rollout in another terminal:

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

9. Set the initial admin user

The chart does not auto-create an initial admin. After definite init returns successfully and the pods are Ready, set INITIAL_ADMIN_EMAIL and INITIAL_ADMIN_PASSWORD on the api Deployment; the api creates the admin record on its next start.

ADMIN_PASSWORD=$(openssl rand -base64 24 | tr -dc 'A-Za-z0-9' | head -c 24)
kubectl set env deploy/definite-api -n definite \
  INITIAL_ADMIN_EMAIL=<your-email> \
  INITIAL_ADMIN_PASSWORD="$ADMIN_PASSWORD"
kubectl rollout status deploy/definite-api -n definite
echo "Admin password: $ADMIN_PASSWORD"

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

The admin bootstrap env vars are only needed to create the initial admin. As of the v0.0.11 install path, this API rollout is expected to complete without a manual lakehouse restart.

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.

Want Google SSO instead of local auth? See the Google SSO guide. You’ll add an auth.oidc block to your config.yaml and re-run definite upgrade — no need to redo the install.

Bedrock IRSA

If you’re using Bedrock as the LLM provider (the default for AWS), Fi authenticates to Bedrock via IRSA: the pod’s ServiceAccount must carry an eks.amazonaws.com/role-arn annotation pointing at the IRSA role Terraform created. Confirm the annotation after definite init, and apply it if it is missing:

BEDROCK_ROLE_ARN=$(terraform output -raw bedrock_irsa_role_arn)

kubectl annotate serviceaccount definite -n definite \
  eks.amazonaws.com/role-arn="$BEDROCK_ROLE_ARN" --overwrite

# Restart the api pod so it picks up the projected token for the new role.
kubectl rollout restart deploy/definite-api -n definite
kubectl rollout status  deploy/definite-api -n definite

A subsequent definite upgrade preserves the annotation (Helm’s three-way merge leaves unmanaged fields alone), but re-apply it if anyone does a helm uninstall + reinstall.

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

Delete the ingress-nginx load balancer before running terraform destroy. definite bootstrap provisions an AWS Network Load Balancer through a Kubernetes Service: LoadBalancer. The NLB is owned by Kubernetes, not Terraform, and its ENIs in the public subnets block terraform destroy with DependencyViolation errors after ~20 minutes of retry.

First, delete the orphaned NLB so Terraform can clean up the VPC:

VPC=$(terraform output -raw vpc_id)
LB_ARN=$(aws elbv2 describe-load-balancers \
  --query "LoadBalancers[?VpcId=='$VPC'].LoadBalancerArn" --output text)
[ -n "$LB_ARN" ] && aws elbv2 delete-load-balancer --load-balancer-arn "$LB_ARN"

Wait 30 to 60 seconds for the ENIs to clear, then destroy the rest with Terraform:

cd definite-aws-terraform
terraform destroy

A couple of safety rails are on by default:

Variable	Default	Effect
`rds_deletion_protection`	`false` (set to `true` for production)	When `true`, RDS refuses to be deleted; flip it to `false` first
`lakehouse_force_destroy`	`false`	Non-empty buckets won’t be deleted; flip it to `true` if you really mean to remove the bucket and its contents

For production teardowns, snapshot RDS and back up the S3 bucket first; once Terraform deletes them, they’re gone.

Troubleshooting

Symptom	Likely cause	Fix
`terraform apply` hangs on EKS	Cluster takes 15-20 min to provision; this is normal	Wait
Lakehouse pod stuck `Pending` on PVC	No default StorageClass	Confirm `gp3` StorageClass is present: `kubectl get storageclass`. The module creates it by default; set `create_gp3_storage_class = true` if you disabled it
`definite doctor` Postgres check fails with “connect timeout” or “could not reach postgres”	RDS is not publicly accessible (no public endpoint); the check is running from a laptop outside the VPC	Expected for private RDS from a laptop. The in-cluster API pods reach RDS over the VPC’s private network. To fully validate before install, run `definite doctor` from a bastion host or an in-cluster pod. Use `--skip-preflight` only for this known private-network check, not for object-store, Kubernetes, license, or LLM failures
LB hostname never appears	Ingress controller isn’t running, or the AWS Load Balancer Controller fights with `ingress-nginx`	`kubectl get pods -n ingress-nginx`; if you installed both controllers, pick one
Brokered URL never becomes ready	The setup broker has not pointed `*.onprem.definite.app` at the NLB yet, or the NLB hostname is wrong	Re-run `definite init --config config.yaml --dns-mode definite-brokered`, confirm `$LB_HOST` matches the ingress Service, and retry before debugging the app
Customer-owned hostname does not work	Customer-owned DNS was selected, but the CNAME does not point at the NLB or the custom cert/private CA path is incomplete	Fix the customer DNS/cert path or switch back to the default Definite-brokered DNS mode for first install
Fi can’t reach Bedrock	The `definite` ServiceAccount isn’t annotated with the Bedrock IRSA role, or the model isn’t enabled in the region	Annotate the SA with the Bedrock IRSA role ARN (see Bedrock IRSA), and request model access in the AWS Bedrock console
You can log in, but every product page or API call returns HTTP 403	The deployment is unlicensed: `config.yaml` has no `license` block, or the key is wrong	Add a `license` block with your Definite-issued key and run `definite upgrade --config config.yaml`. `definite init` prints an `UNLICENSED` warning when the block is missing

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.

​What gets created

​Prerequisites

​Phase 1: Provision AWS infrastructure with Terraform

​1. Configure inputs

​2. Init, plan, apply

​3. Read the outputs

​IRSA vs access key

​Phase 2: Install Definite with the definite CLI

​1. Install the CLI

​2. Point kubectl at the new cluster

​3. Bootstrap cluster prerequisites

​4. Let definite init request Definite-brokered DNS

​5. Build config.yaml

​6. Export secrets

​7. Preflight with definite doctor

​8. Deploy with definite init

​9. Set the initial admin user

​Bedrock IRSA

​Day-2 operations

​Phase 3: Teardown

​Troubleshooting

​Next steps

​Support

What gets created

Prerequisites

Phase 1: Provision AWS infrastructure with Terraform

1. Configure inputs

2. Init, plan, apply

3. Read the outputs

IRSA vs access key

Phase 2: Install Definite with the `definite` CLI

1. Install the CLI

2. Point `kubectl` at the new cluster

3. Bootstrap cluster prerequisites

4. Let `definite init` request Definite-brokered DNS

5. Build `config.yaml`

6. Export secrets

7. Preflight with `definite doctor`

8. Deploy with `definite init`

9. Set the initial admin user

Bedrock IRSA

Day-2 operations

Phase 3: Teardown

Troubleshooting

Next steps

Support