Skip to main content

GCP Automated Deployment

Fully automated production deployment on Google Cloud Platform using Terraform.

Overview​

The GCP deployment automatically provisions:

  • GKE Cluster — Kubernetes cluster for container orchestration
  • Cloud SQL — Managed PostgreSQL database
  • Load Balancers — External access with SSL termination
  • DNS Records — Automatic domain configuration
  • SSL Certificates — Let's Encrypt certificates via cert-manager

Deployment Time: 30-45 minutes

Prerequisites​

Domain & DNS required

Ekai on GCP 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 after deployment completes.

During install you enter this as the DNS zone; Terraform creates a Google Cloud DNS zone and prints Google’s nameservers. After success, delegate the subdomain. Until that propagates (minutes to hours), the URL may not resolve and HTTPS may fail or show a certificate warning.

Before starting, ensure you have:

  • A domain (or subdomain) you own (you may need your domain admin to add nameservers after deployment)
  • GCP account with billing enabled
  • GCP project created with appropriate quotas
  • gcloud CLI installed and authenticated
  • terraform CLI installed (v1.0+)
  • kubectl CLI installed
  • gke-gcloud-auth-plugin installed
  • jq and dig utilities installed

See Prerequisites for detailed installation instructions.

Required GCP Permissions​

Your account needs these roles in the target GCP project:

RolePurpose
Compute AdminCreate and manage VMs, networks
Kubernetes Engine AdminCreate and manage GKE clusters
Service Account AdminCreate service accounts
Cloud SQL AdminCreate and manage databases
DNS AdministratorCreate DNS records

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 GCP Provider​

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

Enter choice [1-4]: 3

Step 5: Dependency Check​

The install verifies required GCP tools and offers to auto-install missing ones:

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

Install missing tools? [Y/n]: Y

Step 6: Configure Deployment​

Provide the following information when prompted:

GCP Project ID​

We recommend creating a new GCP project and using it for the ekai deployment.

Enter your GCP Project ID: my-company-ekai-prod

Environment Name​

We recommend using an identifier that starts with ekai-.

Enter environment name (e.g., ekai-production, ekai-staging): ekai-production

DNS Zone​

You must own this domain (or subdomain). You might need your domain admin to add the nameservers after deployment completes.

Enter your domain (e.g., ekai.yourcompany.com): ekai.yourcompany.com
After install

Delegate the zone at your registrar using the Google nameservers from the success output. See How to delegate a subdomain.

Region​

Enter GCP region [default: us-central1]: us-central1

Step 7: Terraform Execution​

The install automatically:

  1. Downloads the terraform-google-ekai repository
  2. Creates service accounts and credentials
  3. Provisions infrastructure:
    • GKE cluster (3 nodes by default)
    • Cloud SQL PostgreSQL instance
    • Load balancers
    • Cloud DNS zone
    • SSL certificate management
  4. Deploys ekai via Helm charts
  5. Configures ingress and SSL

Step 8: 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 setup2-5 minutes
OAuth authentication1-2 minutes
Terraform planning2-3 minutes
Infrastructure provisioning15-20 minutes
Application deployment3-5 minutes
DNS propagation5-10 minutes
Total30-45 minutes
Progress Monitoring

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

Deployment Success​

Upon successful completion, you will see output similar to:

✓ Deploy complete for env=production.
Generated key/secrets saved at: ./terraform-google-ekai/.self-deploy/production-generated-secrets.txt / ./terraform-google-ekai/.self-deploy/production-deployer-key.json — copy into your password manager, then delete these files.

✓ Ekai is running!

  Ekai:   https://portal.yourcompany.com   (34.X.X.X)

  Note: 34.X.X.X is the ingress IP, shown for reference (e.g. to sanity-check DNS once it propagates) —
  it isn't verified reachable from outside GCP, since that depends on firewall rules this doesn't configure.

  Before yourcompany.com works: delegate it to these nameservers at your domain registrar
  (or parent DNS zone) — add an NS record for yourcompany.com pointing at each:
    ns-cloud-b1.googledomains.com.
    ns-cloud-b2.googledomains.com.
    ns-cloud-b3.googledomains.com.
    ns-cloud-b4.googledomains.com.
  (shown with GCP's trailing dot — your registrar may not want it in the NS record;
  check its own docs/UI to confirm whether to include or drop it.)
  DNS propagation can take anywhere from a few minutes to a few hours. Until it's
  done, the wildcard TLS cert can't be issued either — the URL above will fail or
  show a certificate warning in the meantime.

Use those printed nameservers in the steps below. Until delegation propagates, the ekai URL may not resolve and HTTPS may fail or show a certificate warning.

Service Startup Time

After successful deployment, it can take up to 15 minutes for all services to come online. Please wait 15 minutes 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 Google nameservers from the installer’s success output (usually at least two 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.), you can resume:

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:

Found previous run artifacts for GCP env 'production'.
Retry that deploy instead of starting a new one? [y/N]: y

Step 3: Automatic Resume​

  • Skips all configuration prompts
  • Reads settings from previous run
  • Continues from last Terraform state
  • Resumes infrastructure provisioning
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 GKE cluster:

gcloud container clusters get-credentials ekai-production-gke \
  --region us-central1 \
  --project YOUR_PROJECT_ID

Verify connection:

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

SSL Certificate Provisioning​

SSL certificates are automatically provisioned via Let's Encrypt using cert-manager. This process completes after DNS has propagated.

Check certificate status:

kubectl get certificate -n ekai
kubectl describe certificate ekai-tls -n ekai

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-google-ekai/
terraform state list

GCP Permission Errors​

Verify your account has required roles:

gcloud projects get-iam-policy YOUR_PROJECT_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:user:YOUR_EMAIL"

SSL Certificate Issues​

Wait for DNS propagation, then check:

kubectl logs -n cert-manager deployment/cert-manager

For more detailed troubleshooting, see Troubleshooting Guide.

Next Steps​