Prerequisites & Requirements

Complete these prerequisites before you start installation. They fall into five groups: supported platforms, cloud account access, networking, compute/storage sizing, and local tooling. Work through the pre-install checklist at the end to confirm you have everything.

Supported platforms and versions

Component	Requirement
Kubernetes	1.34 (reference build; EKS or AKS)
Cloud	AWS or Azure (one per environment)
Warehouse	Snowflake or Databricks (one per environment)
Metadata database	PostgreSQL 15 (managed)
Ingress	Envoy Gateway (Gateway API) + cert-manager
GitOps	ArgoCD + Kustomize

Cloud account requirements

You need an account/subscription where you can create a cluster, registry, DNS records, a managed Postgres, and the identities that tie them together.

AWS

• An AWS account with admin (or equivalent) access to run Terraform/Terragrunt.
• A region with capacity for the sizes below (reference deployment uses ap-southeast-1).
• A GitHub OIDC provider and a role for CI to push images to ECR (provisioned by the IaC).

Permissions to provision (Terraform runner):

Service	Why
EKS	Create/manage the cluster, node groups, and addons
EC2 / VPC	VPC, subnets, NAT gateway, security groups, IGW
ECR	Create image repositories
RDS	Create the PostgreSQL instance and parameter group
Route 53	Manage the hosted zone and records
IAM	Create cluster/node roles and Pod Identity roles
Secrets Manager + KMS	Store secrets and allow pods to decrypt them
S3 + (state locking)	Terraform remote state backend

Runtime identity: pods use EKS Pod Identity to assume scoped IAM roles (no static keys). Each service’s role is limited to secretsmanager:GetSecretValue/DescribeSecret on its own secret ARNs plus kms:Decrypt.

Azure

• An Azure subscription with Owner or Contributor + User Access Administrator to run Terraform/Terragrunt (role assignments are created).
• A region with capacity for the sizes below (reference deployment uses australiaeast).
• An Azure AD app + federated credentials for GitHub Actions (provisioned by the IaC).

Permissions to provision (Terraform runner):

Service	Why
AKS	Create/manage the cluster and node pools
Virtual Network	VNet, subnets, NSGs, NAT gateway
Container Registry	Create the ACR (Premium)
PostgreSQL Flexible Server	Create the metadata database
Azure DNS	Manage the delegated DNS subzone
Managed Identity + RBAC	Create user-assigned identities and role assignments
Key Vault	Store secrets (RBAC-authorized)
Storage	Terraform state storage account + container

Runtime identity: pods use AKS Workload Identity — user-assigned managed identities federated to Kubernetes ServiceAccounts via the cluster’s OIDC issuer. cert-manager gets DNS Zone Contributor scoped to the DNS subzone only.

Warehouse access

Databricks

• A Databricks workspace with Unity Catalog enabled.
• A service principal (client ID + secret) Nexa authenticates as.
• A SQL warehouse for query execution and a catalog Nexa manages.
• The service principal needs permission to create/manage schemas, tables, jobs, and pipelines within that catalog, and to use the SQL warehouse.
• You will provide: workspace host/ID, warehouse ID, catalog name, client ID/secret.

Snowflake

• A Snowflake account reachable from your cloud region.
• A service account and role Nexa authenticates as.
• A warehouse for compute and the databases/schemas Nexa manages.
• The role needs privileges to create/manage schemas, tables, and tasks in those databases and to use the warehouse.
• You will provide: account identifier, warehouse, role, and service-account credentials.

Networking

Requirement	Detail
Address space	A VPC/VNet CIDR that doesn’t overlap your existing networks (reference uses /16)
Subnets	Public + private (AWS) or AKS/PE/DB delegated subnets (Azure), across 2 AZs/zones
Egress	NAT gateway for outbound (image pulls, warehouse API, ACME, model calls)
DNS	A zone/subzone you control for the Nexa hostname (e.g. <env>.nexa-drai.com)
TLS	cert-manager + Let’s Encrypt DNS-01, or bring your own certificates
Load balancer	Cloud LB (NLB / Azure LB) fronting Envoy Gateway

Ports (see reference architecture for the full matrix):

Port	Purpose
443 inbound	User/API traffic (TLS at Envoy)
80 inbound	Redirect to 443
5432 outbound (in-cloud)	Pods → managed Postgres
443 outbound	Warehouse API, ACME/DNS, model endpoints

Caution

Confirm your chosen CIDRs do not overlap peered networks or your warehouse’s network — overlapping ranges break VNet/VPC peering and routing to Postgres and (on Azure) Databricks.

Compute and storage sizing

The reference build runs all Nexa services on a single node group/pool. Size for the sum of pod requests below plus headroom.

Resource	Minimum (dev)	Recommended (prod)
Worker nodes	3 × 4 vCPU / 16 GB (e.g. t3.xlarge / Standard_D4s_v5)	5+ nodes, autoscaled
Metadata Postgres	2 vCPU / small (e.g. db.t3.micro / B_Standard_B1ms), 20–32 GB	General-purpose SKU, 128 GB, HA/zone-redundant
Node disk	20–50 GB per node	50–100 GB per node
Registry	ECR / ACR (Premium on Azure)	same

Representative per-service pod requests (reference manifests) — use these to plan node capacity:

Service	CPU request	Memory request	Notes
nexa-web	100m	128Mi
nexa-backend	100m	256Mi
warehouse API	100m	256Mi	+ worker: 500m / 4Gi
nexa-agents-api	300m	512Mi	+ worker
nexa-orchestration-service	2000m	3Gi	large; worker scales to zero
nexa-stt-service	4000m	6Gi	large; deploy only if using speech-to-text

Note

nexa-stt-service (speech-to-text) is the heaviest component (up to 8 vCPU / 10Gi limits). If you don’t use speech features, omit it and save the node capacity.

Local tooling

Install on the workstation or CI runner that performs the install.

Tool	Version	Use
Terraform	≥ 1.5	Apply the IaC
Terragrunt	recent	Wraps Terraform for per-environment state/backends
kubectl	matches 1.34	Interact with the cluster
Kustomize	recent	Render manifests (bundled with kubectl)
Helm	3.x	Install Envoy Gateway / addons
ArgoCD CLI	recent	Optional; drive GitOps sync
Cloud CLI	AWS CLI v2 or Azure CLI	Auth, kubeconfig, registry login
git	recent	Clone IaC and manifest repos

Pre-install checklist

Copy this and tick each item before running the installation.

[ ] Cloud account/subscription with provisioning permissions (see table above)
[ ] Target region chosen and has quota for the node sizes
[ ] Non-overlapping VPC/VNet CIDR reserved
[ ] DNS zone/subzone you control for the Nexa hostname
[ ] Warehouse ready: workspace/account + service principal/account + catalog/db
[ ] Warehouse credentials collected (host/account, IDs, client secret/role)
[ ] GitHub access to the IaC and manifest repositories
[ ] Terraform state backend available (S3 / Azure Storage)
[ ] Secret values prepared for the shared secret (DB, warehouse, GitHub, JWT)
[ ] Local tooling installed (Terraform, Terragrunt, kubectl, Helm, cloud CLI)
[ ] Reviewed the reference architecture and security pages with your security team

When every box is checked, continue to Installation.