Skip to main content

CODITECT Flow Platform - Deployment Guide

Complete guide for deploying the infrastructure to GCP using OpenTofu.

Prerequisites​

Tools Required​

# Install OpenTofu
brew install opentofu

# Verify installation
tofu version

# Install gcloud CLI (if not already installed)
brew install --cask google-cloud-sdk

# Authenticate with GCP
gcloud auth login
gcloud auth application-default login

# Set project
gcloud config set project coditect-citus-prod

GCP Permissions​

Ensure you have the following IAM roles:

  • roles/compute.admin
  • roles/container.admin
  • roles/cloudsql.admin
  • roles/redis.admin
  • roles/iam.serviceAccountAdmin
  • roles/resourcemanager.projectIamAdmin

Initial Setup​

1. Create State Bucket​

# Create GCS bucket for Terraform state (one-time setup)
gsutil mb -p coditect-citus-prod -c STANDARD -l us-central1 gs://coditect-flow-terraform-state

# Enable versioning
gsutil versioning set on gs://coditect-flow-terraform-state

# Set lifecycle rule to keep 10 versions
cat > lifecycle.json <<EOF
{
  "lifecycle": {
    "rule": [
      {
        "action": {"type": "Delete"},
        "condition": {
          "numNewerVersions": 10
        }
      }
    ]
  }
}
EOF

gsutil lifecycle set lifecycle.json gs://coditect-flow-terraform-state
rm lifecycle.json

2. Configure Backend​

# For staging
cd infra/environments/staging
cp ../../backend.tf.example backend.tf
sed -i '' 's/ENVIRONMENT_NAME/staging/' backend.tf

# For production
cd infra/environments/production
cp ../../backend.tf.example backend.tf
sed -i '' 's/ENVIRONMENT_NAME/production/' backend.tf

Deploy Staging Environment​

1. Set Variables​

cd infra/environments/staging

# Create tfvars file
cp terraform.tfvars.example terraform.tfvars

# Edit with secure values
cat > terraform.tfvars <<EOF
project_id  = "coditect-citus-prod"
region      = "us-central1"
db_password = "$(openssl rand -base64 32)"
EOF

2. Initialize and Deploy​

# Initialize Terraform
tofu init

# Review plan
tofu plan -out=staging.tfplan

# Apply (creates all infrastructure)
tofu apply staging.tfplan

3. Post-Deployment Setup​

# Connect to GKE cluster
gcloud container clusters get-credentials coditect-step-staging-gke \
  --zone=us-central1-a \
  --project=coditect-citus-prod

# Create namespace
kubectl create namespace coditect-flow

# Install NATS via Helm
helm repo add nats https://nats-io.github.io/k8s/helm/charts/
helm repo update

# Get generated values file
NATS_VALUES=$(tofu output -raw nats_values_file)

# Install NATS
helm install nats nats/nats -n coditect-flow -f "$NATS_VALUES"

# Verify deployment
kubectl get all -n coditect-flow

4. Retrieve Connection Information​

# Cloud SQL connection string
tofu output cloudsql_connection_name

# Redis connection
tofu output redis_host
tofu output redis_port

# Redis AUTH string
tofu output -raw redis_auth_string

# Save to Secret Manager
gcloud secrets create staging-redis-auth \
  --data-file=<(tofu output -raw redis_auth_string) \
  --replication-policy="automatic"

Deploy Production Environment​

1. Set Variables​

cd infra/environments/production

# Create tfvars file
cp terraform.tfvars.example terraform.tfvars

# Edit with secure values
cat > terraform.tfvars <<EOF
project_id            = "coditect-citus-prod"
region                = "us-central1"
db_password           = "$(openssl rand -base64 32)"
enable_read_replica   = false

# Restrict master access (replace with your IPs)
master_authorized_networks = [
  {
    cidr_block   = "YOUR_OFFICE_IP/32"
    display_name = "Office"
  }
]
EOF

2. Initialize and Deploy​

# Initialize Terraform
tofu init

# Review plan carefully
tofu plan -out=production.tfplan

# Apply (creates all infrastructure)
tofu apply production.tfplan

3. Post-Deployment Setup​

# Connect to GKE cluster (regional)
gcloud container clusters get-credentials coditect-step-production-gke \
  --region=us-central1 \
  --project=coditect-citus-prod

# Create namespace
kubectl create namespace coditect-flow

# Install NATS via Helm
helm repo add nats https://nats-io.github.io/k8s/helm/charts/
helm repo update

# Get generated values file
NATS_VALUES=$(tofu output -raw nats_values_file)

# Install NATS
helm install nats nats/nats -n coditect-flow -f "$NATS_VALUES"

# Verify deployment
kubectl get all -n coditect-flow
kubectl get pvc -n coditect-flow

Kubernetes Deployments​

After infrastructure is provisioned, deploy the application workloads.

1. Create ConfigMaps and Secrets​

# Database connection
kubectl create secret generic cloudsql-credentials \
  -n coditect-flow \
  --from-literal=connection-name=$(tofu output -raw cloudsql_connection_name) \
  --from-literal=database=$(tofu output -raw cloudsql_database_name) \
  --from-literal=username=flow_api \
  --from-literal=password=$(cat terraform.tfvars | grep db_password | cut -d'"' -f2)

# Redis connection
kubectl create secret generic redis-credentials \
  -n coditect-flow \
  --from-literal=host=$(tofu output -raw redis_host) \
  --from-literal=port=$(tofu output -raw redis_port) \
  --from-literal=auth=$(tofu output -raw redis_auth_string)

# NATS connection
kubectl create configmap nats-config \
  -n coditect-flow \
  --from-literal=url=nats://nats.coditect-flow.svc.cluster.local:4222

2. Deploy Flow Platform​

# Apply Kubernetes manifests (once created)
kubectl apply -f ../../k8s/ -n coditect-flow

Monitoring and Verification​

Check Infrastructure Health​

# GKE nodes
kubectl get nodes

# Cloud SQL status
gcloud sql instances describe $(tofu output -raw cloudsql_instance_name)

# Redis status
gcloud redis instances describe $(tofu output -raw redis_instance_name) --region=us-central1

# NATS pods
kubectl get pods -n coditect-flow -l app.kubernetes.io/name=nats
kubectl logs -n coditect-flow -l app.kubernetes.io/name=nats --tail=50

Test Connectivity​

# Test Cloud SQL connection
kubectl run -it --rm psql-test \
  --image=postgres:15 \
  --restart=Never \
  -n coditect-flow \
  -- psql "host=$(tofu output -raw cloudsql_private_ip) dbname=$(tofu output -raw cloudsql_database_name) user=flow_api password=YOUR_PASSWORD sslmode=require"

# Test Redis connection
kubectl run -it --rm redis-test \
  --image=redis:7-alpine \
  --restart=Never \
  -n coditect-flow \
  -- redis-cli -h $(tofu output -raw redis_host) -a $(tofu output -raw redis_auth_string) PING

# Test NATS connection
kubectl run -it --rm nats-test \
  --image=natsio/nats-box:latest \
  --restart=Never \
  -n coditect-flow \
  -- nats context save local --server=nats://nats.coditect-flow.svc.cluster.local:4222 && nats server info

Updating Infrastructure​

Modify and Apply Changes​

cd infra/environments/staging  # or production

# Make changes to variables or module configs

# Plan changes
tofu plan -out=update.tfplan

# Review carefully
tofu show update.tfplan

# Apply changes
tofu apply update.tfplan

Upgrade GKE Cluster​

# Check available versions
gcloud container get-server-config --region=us-central1

# Update in main.tf:
# release_channel = "REGULAR"  # Auto-upgrades within channel

# Or manual upgrade:
gcloud container clusters upgrade coditect-step-staging-gke \
  --zone=us-central1-a \
  --cluster-version=VERSION

Disaster Recovery​

Backup State​

# State is automatically versioned in GCS
# To download current state:
gsutil cp gs://coditect-flow-terraform-state/env/staging/default.tfstate ./backup-$(date +%Y%m%d).tfstate

Restore from Backup​

# List versions
gsutil ls -a gs://coditect-flow-terraform-state/env/staging/

# Copy specific version to current
gsutil cp gs://coditect-flow-terraform-state/env/staging/default.tfstate#VERSION \
  gs://coditect-flow-terraform-state/env/staging/default.tfstate

Teardown (Use with Caution)​

Destroy Staging​

cd infra/environments/staging

# Review what will be destroyed
tofu plan -destroy

# Destroy (prompts for confirmation)
tofu destroy

# Or with auto-approve (dangerous)
tofu destroy -auto-approve

Destroy Production​

WARNING: This will delete all production data.

cd infra/environments/production

# Disable deletion protection first
# Edit main.tf: set deletion_protection = false for cloudsql and redis

tofu apply

# Then destroy
tofu destroy

Troubleshooting​

Common Issues​

1. API Not Enabled​

Error: Error creating Instance: googleapi: Error 403: Access Not Configured

Solution: Enable required APIs manually:

gcloud services enable compute.googleapis.com
gcloud services enable container.googleapis.com
gcloud services enable sqladmin.googleapis.com
gcloud services enable redis.googleapis.com

2. Quota Exceeded​

Error: Quota exceeded

Solution: Request quota increase in GCP Console:

  • Compute Engine API → Quotas
  • Increase CPU, disk, or IP quotas

3. VPC Peering Conflict​

Error: Error creating private service connection

Solution: Delete existing peering and retry:

gcloud services vpc-peerings delete \
  --service=servicenetworking.googleapis.com \
  --network=coditect-step-staging-vpc

4. GKE Master Unreachable​

Solution: Check authorized networks and add your IP:

gcloud container clusters update coditect-step-staging-gke \
  --zone=us-central1-a \
  --enable-master-authorized-networks \
  --master-authorized-networks YOUR_IP/32

Cost Optimization​

Staging Cost Reduction​

  • Use BASIC tier Redis instead of STANDARD_HA
  • Use zonal GKE cluster instead of regional
  • Use ZONAL Cloud SQL instead of REGIONAL
  • Enable preemptible nodes for non-critical workloads
  • Set disk_type = "pd-standard" instead of "pd-ssd"

Production Cost Monitoring​

# Set up budget alerts
gcloud billing budgets create \
  --billing-account=BILLING_ACCOUNT_ID \
  --display-name="CODITECT Flow Production" \
  --budget-amount=2000 \
  --threshold-rule=percent=50 \
  --threshold-rule=percent=90 \
  --threshold-rule=percent=100

Next Steps​

After infrastructure deployment:

  1. Deploy application containers to GKE
  2. Configure Ingress and SSL certificates
  3. Set up monitoring dashboards (Grafana)
  4. Configure alerting rules (Prometheus)
  5. Enable backup automation
  6. Implement CI/CD pipeline for deployments

Track: AO.19 | Owner: AZ1.AI INC | Lead: Hal Casteel