Skip to main content

Deploying a Region

Assumptions​

  • This document uses dev.sgp-1.cogrion.com as implementation example — development environment on AWS Singapore (ap-southeast-1).
RepositoryPurpose
cogrion-terraformCloud infrastructure
cogrion-gitopsArgoCD apps, Helm charts, environment values

This page documents the actual procedure for deploying a new region or environment. For the architectural rationale behind these steps see ADR: Deploying a Region.

Global Prerequisites​

These must exist once before any region is deployed. They are shared across all environments and regions.

PrerequisiteStatusNotes
cogrion.com root domain registered (GoDaddy)TODO
cogrion.com DNS zone active in CloudflareTODOCurrently this DNS zone for root domain is managed on AWS Route 53
Cloudflare Workers deployed (auth.cogrion.com, cplane.cogrion.com/lookup)TODOGlobal auth proxy and tenant→region routing
Cloudflare KV namespace (tenant→region map)TODOWritten at workspace provision time
Dashboard UI deployed (app.cogrion.com)TODO
Root CA in AWS Secrets Manager (ap-southeast-1)TODOShared PKI root for all regional OpenBao instances
Primary region sgp-1TODOAll other regions resolve principals from sgp-1

Deployment Sequence​

Phase 1 — AWS Infrastructure (Terraform)​

  1. Prepare directory envs/dev-sgp-1/ in cogrion-terraform.
  2. Update terraform.tfvars and backend.tf for dev-sgp-1.
  3. Run tofu apply — provisions:
    • VPC, subnets, NAT, security groups
    • EKS cluster + node groups (dev-sgp-1)
    • RDS instance
    • Route53 hosted zone (dev.sgp-1.cogrion.com)
    • S3 buckets (cogrion-dev-sgp-1-artifacts, cogrion-dev-sgp-1-exports)
    • IAM roles (cluster, node, IRSA)

Phase 2 — DNS Delegation​

  1. Add NS records in Cloudflare pointing dev.sgp-1.cogrion.com → the new Route53 zone nameservers.

Phase 3 — Cluster Bootstrap​

  1. Bootstrap ArgoCD and apply cluster resources — see GitOps: Bootstrap a new cluster.

    kubectl apply -n argocd -k https://github.com/argoproj/argo-cd/manifests/cluster-install?ref=v2.12.0
    kubectl apply -f argocd/_bootstrap/dev-sgp-1/bootstrap.yaml
    kubectl apply -f argocd/app-roots/dev-sgp-1.yaml

  2. Apply cluster-level secrets (image pull, RDS credentials, inter-region service token).

Phase 4 — PKI and TLS​

  1. Deploy OpenBao into the cluster.
  2. Import the shared root CA from AWS Secrets Manager into OpenBao's PKI backend.
  3. Deploy cert-manager and configure it to use OpenBao as the issuer.

Phase 5 — Platform Services (ArgoCD)​

  1. Copy ArgoCD app manifests and Helm values from an existing region into cogrion-gitops:

    cp -r argocd/apps/prod-sgp-1   argocd/apps/dev-sgp-1
    cp -r values/prod-sgp-1        values/dev-sgp-1

    Update all domain and bucket values in values/dev-sgp-1/ to use dev.sgp-1.cogrion.com, cogrion-dev-sgp-1-artifacts, etc.

  2. Sync ArgoCD — deploys in dependency order:

    • Keycloak
    • Temporal (server + workers)
    • Control plane API
    • Observability stack (Prometheus, Grafana, Loki)

Phase 6 — Region Registration​

  1. Update Cloudflare KV to route new tenants to dev.sgp-1.cogrion.com at signup.
  2. Since dev-sgp-1 is a secondary region (not sgp-1 primary): set PRIMARY_CPLANE_API_URL=https://cplane.sgp-1.cogrion.com and INTER_REGION_SERVICE_TOKEN in Helm values.

Phase 7 — Smoke Test​

  1. Create a test tenant assigned to dev-sgp-1 and verify the full auth flow end-to-end.
  2. Provision a test workspace and confirm DNS delegation, cert issuance, and cluster agent bootstrap token flow.

New Environment vs New Region​

  • New environment (e.g. dev-sgp-1): Phase 1 is a subset — no new VPC if sharing; new RDS and S3 only. Route53 zone is a subdomain of the existing regional zone.
  • New region: Full Phase 1 including VPC and EKS. Phase 2 adds a new top-level NS delegation.

Teardown​

Drain workspaces → remove Cloudflare KV entry → delete ArgoCD apps → tofu destroy. The shared root CA and global Cloudflare layer are unaffected.