Installation Guide

This guide takes you from an empty cloud account to a healthy Nexa deployment. It provisions infrastructure with the supplied Terraform/Terragrunt, publishes images to your registry, loads secrets, deploys the services with ArgoCD + Kustomize, and validates the result. Complete the prerequisites first — this guide assumes the checklist is done.

Note

Commands and resource names below match the reference deployment (region ap-southeast-1 on AWS / australiaeast on Azure, cluster name aws-iac-<env> / nexa-<env>-aks). Substitute your own environment name, region, and hostnames throughout.

Step 1 — Confirm prerequisites

1. Verify your local tooling resolves:

   terraform version && kubectl version --client && helm version

   Expected: Terraform ≥ 1.5, a kubectl client on 1.34, and Helm 3.x — no errors.

2. Authenticate to your cloud and confirm the target account/subscription:

   AWS

   aws sts get-caller-identity

   Expected: JSON showing your account ID (e.g. "Account": "930816733209") and role ARN.

   Azure

   az account show --query "{sub:id, tenant:tenantId, name:name}" -o table

   Expected: a row with your subscription ID and tenant — the intended target.

Step 2 — Provision infrastructure with IaC

Clone the IaC repository for your cloud, then apply per environment with Terragrunt. This creates the cluster, registry, DNS, managed Postgres, networking, and identities.

AWS

1. Initialize the state backend (first time only), then apply:

   cd aws-iac
   terragrunt run-all plan  --terragrunt-working-dir . -- -var-file=environments/dev.tfvars
   terragrunt run-all apply --terragrunt-working-dir . -- -var-file=environments/dev.tfvars

   Expected: a plan summary, then Apply complete! per module (network, eks, ecr, rds, route53, IAM/pod-identity).

2. Wire kubectl to the new cluster:

   aws eks update-kubeconfig --name aws-iac-dev --region ap-southeast-1
   kubectl get nodes

   Expected: Added new context ..., then a list of nodes in Ready state.

Azure

1. Apply the numbered stacks in order (00-bootstrap first for state, then 02→09):

   cd nexa-azure-app-iac
   # bootstrap state storage (run once, plain terraform)
   terraform -chdir=stacks/00-bootstrap init && terraform -chdir=stacks/00-bootstrap apply
   # remaining stacks via terragrunt
   terragrunt run-all apply --terragrunt-working-dir . -- -var-file=environments/dev.tfvars

   Expected: Apply complete! per stack (identity, network, acr, aks, data, databricks, observability, dns, workload-identities).

2. Wire kubectl to the new cluster:

   az aks get-credentials --resource-group rg-nexa-dev --name nexa-dev-aks
   kubectl get nodes

   Expected: Merged ... as current context, then nodes in Ready state.

Danger

terragrunt run-all apply creates billable cloud resources and can be destructive on re-runs. Always review the plan output before applying, and never point Terragrunt at the wrong *.tfvars — applying prod.tfvars against a dev account (or vice versa) can replace live infrastructure. Terraform state is authoritative; do not edit resources by hand out-of-band.

Step 3 — Publish images to your registry

DataReadyAI provides the Nexa images; you host them in your registry. In the reference setup, GitHub Actions builds and pushes to the registry via OIDC (no static keys), producing tags like develop-<sha> in lower environments and semantic versions (v1.0.0) in production.

AWS

aws ecr get-login-password --region ap-southeast-1 \
  | docker login --username AWS --password-stdin \
    930816733209.dkr.ecr.ap-southeast-1.amazonaws.com
aws ecr describe-repositories --region ap-southeast-1 \
  --query "repositories[].repositoryName" -o text

Expected: Login Succeeded, then repository names such as aws-iac-nexa-web, aws-iac-nexa-backend, aws-iac-nexa-databricks-api, aws-iac-nexa-agents-api.

Azure

az acr login --name acrnexadev001
az acr repository list --name acrnexadev001 -o table

Expected: Login Succeeded, then the Nexa repositories (nexa-web, nexa-backend, warehouse API, nexa-agents-api, …).

Step 4 — Load secrets

Nexa reads its configuration from a shared secret in your cloud secret store, mounted into pods by the Secrets Store CSI driver and synced to a Kubernetes Secret. Populate it before deploying, or pods will crash-loop on missing config.

Required keys include: Postgres connection (PG_HOST, PG_PORT, PG_DATABASE, PG_USERNAME, PG_PASSWORD), warehouse connection (Databricks: DATABRICKS_HOST, DATABRICKS_CLIENT_ID, DATABRICKS_CLIENT_SECRET, DATABRICKS_WAREHOUSE_ID, DATABRICKS_CATALOG; Snowflake: the equivalent account/role/warehouse keys), auth secrets (NEXA_AUTH_JWT_SECRET, NEXA_SERVICE_AUTH_TOKEN), and GITHUB_TOKEN.

AWS

aws secretsmanager create-secret --name nexa-shared-secret-dev \
  --secret-string file://nexa-shared-secret.dev.json \
  --region ap-southeast-1

Expected: JSON with the secret ARN and Name: nexa-shared-secret-dev.

Azure

az keyvault secret set --vault-name kv-nexa-dev \
  --name nexa-shared-secret-dev \
  --file nexa-shared-secret.dev.json

Expected: JSON describing the created secret version.

Caution

Keep secret values out of Git and out of your shell history (use --file/file://, not inline --secret-string '{...}'). The service ServiceAccounts are already granted read access to their scoped secrets by the IaC — do not widen those grants.

Step 5 — Install platform components

Install Envoy Gateway (ingress), cert-manager (TLS), and ArgoCD (GitOps) from the manifest repository.

1. Install Envoy Gateway and cert-manager, then apply the DNS-01 ClusterIssuer:

   kubectl apply -f infrastructure/envoy-gateway/core/
   kubectl apply -f infrastructure/cert-manager/cluster-issuer-dns01.yaml
   kubectl -n envoy-gateway-system get pods
   kubectl -n cert-manager get clusterissuer

   Expected: Envoy Gateway pods Running; the letsencrypt-prod-dns01 ClusterIssuer shows READY: True.

2. Install ArgoCD and register the app-of-apps (GitOps root):

   kubectl create namespace argocd
   kubectl apply -n argocd -f argocd/bootstrap/app-of-apps.yaml
   kubectl -n argocd get applications

   Expected: ArgoCD Application objects listed for each Nexa service.

Step 6 — Deploy Nexa services

ArgoCD syncs the Kustomize overlay for your environment. You can let it auto-sync or trigger it explicitly.

argocd app sync -l app.kubernetes.io/part-of=nexa
# or, without the ArgoCD CLI:
kubectl apply -k overlays/dev
kubectl get pods -A -l app.kubernetes.io/part-of=nexa

Expected: each Nexa Deployment reaches Running with ready replicas (for example dev-nexa-web, dev-nexa-backend, the warehouse API for your platform, dev-nexa-agents-api, dev-nexa-orchestration-service).

Note

Deploy the warehouse API that matches your choice — nexa-databricks-api or nexa-snowflake-api. The orchestration worker may show 0 replicas by design: KEDA scales it up only when the work queue has pending items.

Step 7 — Validate health

1. Confirm pods and certificates:

   kubectl get pods -A -l app.kubernetes.io/part-of=nexa
   kubectl get certificate -A

   Expected: all pods Running/Ready; the gateway certificate (e.g. nexa-gateway-tls-dev) shows READY: True.

2. Hit a service health endpoint through the gateway:

   curl -si https://dev.nexa-drai.com/health-check | head -n 1

   Expected: HTTP/2 200. (The warehouse API health path is /health; nexa-agents-api uses /api/v1/health.)

3. Confirm DNS resolves to your load balancer:

   dig +short dev.nexa-drai.com

   Expected: the load balancer’s address (an NLB hostname on AWS, a public IP on Azure).

Step 8 — First-use smoke test

1. Open the UI at your Nexa hostname (e.g. https://dev.nexa-drai.com/) and sign in.
2. Confirm the warehouse connection is live by creating a data source and browsing the catalog — see Adding a data source.
3. Confirm GitHub integration by checking that generated pipeline code can be committed — see GitHub integration.

If any check fails, see the operations guide and configuration reference. Once healthy, hand off day-2 operations to your platform team.