Skip to main content

AWS Automated Deployment

Fully automated production deployment on Amazon Web Services using Terraform.

Overview​

The AWS deployment automatically provisions:

  • EKS Cluster — Kubernetes cluster for container orchestration
  • RDS — Managed PostgreSQL database
  • Application Load Balancer — External access with SSL termination
  • Route53 Records — Automatic domain configuration
  • ACM Certificates — TLS certificates via AWS Certificate Manager

Deployment Time: 30-45 minutes

Prerequisites​

Domain & DNS required

Ekai on AWS needs a domain or subdomain you control (for example ekai.yourcompany.com) to host the client-facing web app.

You must own the domain and be able to configure its nameservers at your registrar or parent DNS zone. You might need your domain admin to add the nameservers partway through deployment.

During install you enter this as the DNS zone; Terraform creates a Route53 zone and prints AWS's nameservers — before the rest of the infrastructure is created. Delegate the subdomain at that point and wait for it to propagate. Unlike GCP, AWS Certificate Manager validates the TLS certificate synchronously as part of the deploy, so the installer pauses here until delegation is confirmed rather than finishing first and catching up afterward.

Before starting, ensure you have:

  • A domain (or subdomain) you own (you may need your domain admin to add nameservers partway through deployment)
  • AWS account with billing enabled
  • AWS credentials configured (aws configure, SSO, or a named profile)
  • terraform CLI installed (v1.9+)
  • kubectl CLI installed
  • jq, dig, htpasswd, and openssl utilities installed

See Prerequisites for detailed installation instructions.

Required AWS Permissions​

Unlike the long-lived identity Terraform ultimately runs as, the account you authenticate with to start the install only needs enough access to create one scoped IAM user and two IAM policies — it never touches EKS/RDS/the VPC/etc. directly. In practice, an account with AdministratorAccess (or broad IAM/account-admin rights) satisfies this with no further thought. If your organization wants the precise minimum instead, the exact IAM policy document is in terraform-aws-ekai's PERMISSIONS.md:

Permissions neededPurpose
iam:CreateUser / GetUser / DeleteUserCreate the scoped deployer IAM user (ekai-terraform-<env>)
iam:CreatePolicy / CreatePolicyVersion / GetPolicy / GetPolicyVersion / ListPolicyVersions / DeletePolicyVersionCreate and maintain the deployer's two IAM policies
iam:AttachUserPolicy / DetachUserPolicyAttach those policies to the deployer user
iam:ListAccessKeys / CreateAccessKey / DeleteAccessKey / UpdateAccessKeyIssue the deployer a fresh access key on every run
sts:GetCallerIdentityConfirm who's currently authenticated

The deployer user Terraform actually runs as is created and scoped for you — you never author or review its policies by hand.

Installation Steps​

Step 1: Start from the licensing portal​

Go to licensing.ekai.ai and follow the install instructions shown there.

Step 2: Authenticate with ekai​

  • Browser opens for OAuth login
  • Log in with your ekai credentials
  • Authorize the deployment
  • Return to terminal

Step 3: Select Cloud Deployment​

Choose deployment type:
1) Local (Docker)
2) Cloud

Enter your choice [1-2]: 2

Step 4: Select AWS Provider​

Which cloud provider?
  1) AWS
  2) Azure
  3) GCP
  4) Other (manual)

Enter choice [1-4]: 1

Step 5: Dependency & Permission Check​

The install verifies required AWS tools and checks that your currently-authenticated identity can bootstrap a deployment, offering to auto-install missing tools:

Checking AWS credentials/permissions...
✓ Identity: arn:aws:iam::123456789012:user/you
✓ Sufficient permissions to bootstrap a deployment

Checking dependencies...
✓ AWS CLI found
✓ terraform found
✗ kubectl not found

Install missing tools? [Y/n]: Y

Step 6: Configure Deployment​

Provide the following information when prompted:

AWS Region​

AWS region [us-east-1]: us-east-1

Environment Name​

The environment name becomes part of every AWS resource this creates (the EKS cluster, the IAM deployer user, the S3 state bucket, ...) — it must be unique per deployment, and 20 characters or fewer.

Environment name: ekai-production

DNS Zone​

You must own this domain (or subdomain). Terraform creates the Route53 zone for it before the rest of the infrastructure — you'll delegate it to AWS's nameservers at your registrar at that point, during the install (not after).

DNS zone (e.g. example.com): ekai.yourcompany.com
Delegation happens mid-install

Unlike GCP, the installer pauses right after creating the Route53 zone and waits for you to delegate it — see How to delegate a subdomain below. This is because AWS's certificate validation is synchronous and would otherwise block the rest of the deploy indefinitely.

Step 7: DNS Delegation (blocking)​

The installer creates the Route53 zone first, then prints its nameservers and waits:

════════ DNS delegation required ════════
Add an NS record for ekai.yourcompany.com at your domain registrar (or your
parent DNS zone) pointing at each of these nameservers:
  ns-111.awsdns-11.com.
  ns-222.awsdns-22.net.
  ns-333.awsdns-33.org.
  ns-444.awsdns-44.co.uk.

Checking DNS delegation (this can take several minutes to propagate)...

See How to delegate a subdomain for the exact steps. Once delegation is confirmed, the installer proceeds automatically.

Step 8: Terraform Execution​

Once DNS delegation is confirmed, the install automatically:

  1. Downloads the terraform-aws-ekai repository
  2. Creates the scoped IAM deployer user and its policies
  3. Provisions infrastructure:
    • EKS cluster
    • RDS PostgreSQL instance
    • Application Load Balancer
    • ACM certificate (validated against the Route53 zone from Step 7)
  4. Deploys ekai via Helm charts
  5. Configures ingress and SSL

Step 9: Save Credentials​

Generated keys and secrets are saved under .self-deploy/. Copy them into your password manager, then delete the local files.

Security

These files provide administrative access to your deployment. Store them securely and remove them from disk after saving.

Expected Timeline​

PhaseDuration
Dependency & permission check2-5 minutes
OAuth authentication1-2 minutes
Route53 zone creation + DNS delegation5-60 minutes (depends on your registrar)
Infrastructure provisioning15-20 minutes
Application deployment3-5 minutes
Total30-45 minutes (plus however long delegation takes)
Progress Monitoring

The install displays real-time progress. Infrastructure provisioning is the longest automatic phase as AWS creates compute resources, databases, and networking components.

Deployment Success​

Upon successful completion, you will see output similar to:

✓ Deploy complete for env=ekai-production.
Generated credentials saved at: ./terraform-aws-ekai/.self-deploy/ekai-production-generated-secrets.txt — copy into your password manager, then delete this file.

✓ Ekai is running!

  Ekai:   https://portal.yourcompany.com

Note: Service startup can take a few minutes after the apply completes.
Service Startup Time

After successful deployment, it can take up to 15 minutes for all services to come online. Please wait before accessing or using the web app.

How to delegate a subdomain​

Steps at your registrar (or parent DNS)
  1. Log in to the DNS management panel for your root domain (where primary DNS is hosted).
  2. Create new records of type NS.
  3. In the name field, enter only the subdomain label (for example ekai if the zone is ekai.yourcompany.com).
  4. In the value/destination fields, add the AWS nameservers from the installer's output (usually four NS records).
  5. Save the records and wait for DNS propagation (often minutes to a few hours).

Resume Interrupted Deployments​

If deployment fails or is interrupted (network issues, timeout, etc.), re-run the install:

Step 1: Start the install again​

Return to licensing.ekai.ai and follow the install instructions again.

Step 2: Choose to Resume​

The install detects previous artifacts and offers to resume rather than start over.

Step 3: Automatic Resume​

  • Skips configuration prompts already answered
  • Reads settings from the previous run's tfvars
  • The Route53 zone and any already-created resources are reused, not recreated
  • Continues from last Terraform state
Idempotent Operations

Terraform operations are idempotent — re-running is safe and will only create missing resources, not duplicate existing ones.

Accessing the Kubernetes Cluster​

Connect to your EKS cluster:

aws eks update-kubeconfig --name ekai-production-eks --region us-east-1

Verify connection:

kubectl get pods -n ekai
kubectl get svc -n ekai

SSL Certificate Provisioning​

TLS certificates are provisioned via AWS Certificate Manager and validated against the Route53 zone created in Step 7 — this happens during the deploy, not after, so a successful install means the certificate is already valid.

Check certificate status:

aws acm list-certificates --region us-east-1
aws acm describe-certificate --certificate-arn <arn> --region us-east-1

Troubleshooting​

Tool Installation Failures​

If auto-installation fails, install the required tools using the official documentation in Prerequisites, then start the install again from licensing.ekai.ai.

Terraform Errors​

Check Terraform state:

cd .self-deploy/terraform-aws-ekai/
terraform state list

AWS Permission Errors​

Confirm your current identity and re-run the permission check manually:

aws sts get-caller-identity
aws iam simulate-principal-policy \
  --policy-source-arn <your ARN> \
  --action-names iam:CreateUser iam:AttachUserPolicy iam:CreateAccessKey

Stale AWS Credentials​

If commands fail with InvalidClientTokenId or a similar authentication error right at the start, check for stale environment variables overriding your real credentials:

env | grep -i AWS_
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN
aws sts get-caller-identity   # should succeed and show your real identity

SSL Certificate Issues​

Since validation happens during the apply, a stuck certificate almost always means DNS delegation (Step 7) isn't actually propagated yet:

dig NS ekai.yourcompany.com

For more detailed troubleshooting, see Troubleshooting Guide.

Next Steps​