Cloud Deployment Guide

This guide covers deploying ubTrace on AWS using Terraform for infrastructure provisioning and Helm for Kubernetes deployment.

Architecture Overview

ubTrace on AWS EKS uses the following managed services:

        graph TB
    subgraph AWS["AWS Account"]
        subgraph VPC["VPC"]
            ALB["ALB<br/>(internet-facing)"]

            subgraph EKS["EKS Cluster"]
                API["API<br/>(NestJS)"]
                Frontend["Frontend<br/>(Next.js)"]
                Worker["Worker<br/>(pipeline)"]
                Builder["Builder<br/>(Sphinx)"]
                Keycloak["Keycloak<br/>(OIDC)"]
                EFS[("EFS<br/>shared pipeline volumes")]
            end

            subgraph Managed["Managed Services"]
                RDS_App[("RDS PostgreSQL<br/>(application)")]
                RDS_KC[("RDS PostgreSQL<br/>(auth)")]
                Redis[("ElastiCache<br/>Redis")]
                OpenSearch[("OpenSearch")]
            end

            subgraph Security["Security"]
                KMS["KMS<br/>(encryption)"]
                CloudTrail["CloudTrail<br/>(audit)"]
                IAM["IAM / IRSA<br/>(pod identity)"]
                SSM["SSM<br/>(secrets)"]
            end
        end

        ECR["ECR or Customer Registry<br/>(container images)"]
    end

    ALB -->|api.domain.com| API
    ALB -->|ubtrace.domain.com| Frontend
    ALB -->|keycloak.domain.com| Keycloak

    API --> RDS_App
    API --> Redis
    API --> OpenSearch
    API --> EFS
    Worker --> RDS_App
    Worker --> OpenSearch
    Worker --> EFS
    Builder --> EFS
    Keycloak --> RDS_KC
    EKS -.->|pull images| ECR

The deployment flow follows this sequence:

        graph LR
    A["1. Terraform<br/>provision infra"] --> B["2. Push images<br/>to registry"]
    B --> C["3. Generate<br/>Helm values"]
    C --> D["4. Helm install<br/>on EKS"]
    D --> E["5. Verify<br/>deployment"]

Prerequisites

Tools:

  • OpenTofu >= 1.5.7 (recommended) or Terraform >= 1.5.7

  • AWS CLI v2 configured with appropriate IAM credentials

  • Helm 3.12+

  • kubectl configured for the target cluster

  • Docker (for image loading/pushing)

AWS Resources:

  • An AWS account with permissions to create VPC, EKS, RDS, ElastiCache, OpenSearch, EFS, KMS, CloudTrail, ECR, ALB, IAM roles

  • A domain name and Route 53 hosted zone (or external DNS)

  • An ACM certificate for TLS (or cert-manager)

Sizing Estimates:

Tier

Description

Instance Types

Est. Monthly Cost

Development

Single-AZ, small

t3.large nodes

~$100

Staging

Single-AZ, med

m6i.large nodes

~$300

Production

Multi-AZ, HA

m6i.xlarge nodes

~$1,500

Image Delivery

ubTrace supports two image delivery strategies:

Option A: Amazon ECR (recommended for AWS)

Uses Terraform-provisioned ECR repositories. EKS nodes authenticate to ECR natively via IAM — no image pull secrets needed.

# Push images from offline bundle to ECR
./scripts/ecr-push.sh --region eu-central-1 --version 1.1.0

Option B: Customer Registry (Harbor, Nexus, GitLab)

Use the existing offline-mirror.sh script to push to any OCI-compatible registry. Requires imagePullSecrets in Helm values.

# Push to private registry
docker login harbor.corp.example
./scripts/offline-mirror.sh --registry harbor.corp.example/ubtrace --version 1.1.0

Quick Start

# 1. Bootstrap Terraform state backend
cd infra/terraform
./scripts/bootstrap-state.sh my-state-bucket eu-central-1 my-lock-table

# 2. Configure environment
cp environments/dev.tfvars my-env.tfvars
# Edit my-env.tfvars with your AWS settings

# 3. Provision infrastructure (use tofu or terraform)
tofu init -backend-config=environments/backend-staging.hcl
tofu apply -var-file=my-env.tfvars

# 4. Push images
./scripts/ecr-push.sh --region eu-central-1 --version 1.1.0

# 5. Generate Helm values
./scripts/terraform-to-helm.sh --domain yourdomain.com

# 6. Deploy
helm install ubtrace deploy/helm/ubtrace \
  -f deploy/helm/ubtrace/values-eks.yaml \
  -f values-customer.yaml

Or use the all-in-one orchestrator:

./scripts/cloud-deploy.sh \
  --env dev --region eu-central-1 \
  --domain yourdomain.com --auto-approve

Step-by-Step Manual Deployment

See the sections above for a guided walkthrough. For full variable reference, see Configuration Reference. For day-2 operations, see Operations Guide.

Air-Gapped Deployments

For environments with no internet access after initial setup:

  1. Create VPC endpoints for ECR, S3, and EKS

  2. Push images to ECR from a bastion host with internet

  3. Configure global.imagePullSecrets if using non-ECR registries

  4. All managed services (RDS, ElastiCache, OpenSearch) are VPC-internal by default

Security & Compliance

The Terraform modules implement TISAX/ISO 27001 controls:

  • Encryption at rest: KMS for RDS, ElastiCache, OpenSearch, EFS, EBS, ECR

  • Encryption in transit: TLS for all service connections, ALB HTTPS

  • Audit logging: CloudTrail with KMS-encrypted S3 storage

  • Network isolation: Private subnets for data tier, security groups

  • Identity: IRSA for pod-level IAM roles, no shared credentials

  • Secret management: SSM Parameter Store (encrypted) for passwords