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​

Before starting, ensure you have:

  • 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
  • A domain (or subdomain) to configure the deployment and host ekai’s client-facing web app

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​

Enter your domain (e.g., portal.yourcompany.com): portal.yourcompany.com

Region​

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

You must own the domain and have access to update its DNS records. The install will provide nameserver information if needed.

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.

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

DNS Configuration​

If DNS was not configured automatically, follow the nameserver delegation instructions from the post-deployment output at your domain registrar. Propagation can take a few minutes to a few hours.

Verify DNS:

dig portal.yourcompany.com

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​