LiteLLM 双云 Terraform 部署栈：AWS ECS Fargate 与 GCP Cloud Run 组件化代理实战指南

本指南以仓库中 terraform/litellm/README.md 为骨架，系统讲解 LiteLLM 项目提供的两套开箱即用 Terraform 模块：将 componentized LiteLLM proxy（gateway / backend / ui 三个独立容器）分别部署到 AWS（ECS Fargate + Aurora Postgres + ElastiCache + S3）与 GCP（Cloud Run + Cloud SQL + Memorystore + GCS）的完整过程。读完本文，你将掌握两个栈的资源构成与路径路由规则、模块化调用（for_each / count 多租户）的设计原理、proxy_config 等核心输入项的参数语义，以及从单命令 apply 到生产级 TLS / 数据保留 / 观测接入的落地手法。

背景：组件化拆分与两个栈的总体定位

LiteLLM 在 helm chart（helm/litellm）与 Docker 入口（gateway/Dockerfile、backend/Dockerfile）中采用了 gateway / backend / ui 三容器拆分：gateway 负责 LLM 数据面，backend 负责管理面，ui 提供 Next.js 管理后台。Terraform 模块把这一拆分原样搬到两大公有云，形成两个自包含、可复用的模块：

Stack	计算	数据库（writer + reader）	缓存	对象存储	公网入口
terraform/litellm/aws	ECS Fargate	Aurora Postgres（IAM 认证）	ElastiCache	S3	Application Load Balancer
terraform/litellm/gcp	Cloud Run	Cloud SQL Postgres（口令认证）	Memorystore	GCS	External HTTPS LB

每个模块各自创建独立 VPC 与托管数据组件；从各栈的 examples/default/ 根模块放入 tfvars 文件后执行 terraform apply 即可一键部署。两个栈都支持带类型的 proxy_config 输入（对应 helm chart 的 gateway.config.proxy_config），并支持按组件追加普通环境变量与 Secret Manager 引用。

三个组件（deployable）

组件	默认镜像	端口	职责
gateway	ghcr.io/berriai/litellm-gateway:main-stable	4000	LLM 数据面（/v1/chat/completions、/v1/embeddings…）
backend	ghcr.io/berriai/litellm-backend:main-stable	4001	管理 API（/key/*、/user/*、/team/*、/model/*…）
ui	ghcr.io/berriai/litellm-ui:main-stable	3000	nginx 托管的 Next.js 静态 Dashboard

此外两栈还使用第四个镜像 litellm-migrations（slim 镜像），仅供一次性迁移任务运行 Prisma 迁移后即退出。

无 provider 模块设计：为什么能 for_each

两个模块在自身目录的 versions.tf（如 terraform/litellm/aws/versions.tf）中不声明任何 provider 块，只声明 required_providers 约束，由调用方注入 provider 配置。由此模块可以被 count / for_each / depends_on 组合复用，region、assume-role / 服务账号模拟、provider alias、default_tags 完全由调用方控制。文档给出了内嵌调用骨架：

module "litellm" {
  source = "github.com/BerriAI/litellm//terraform/litellm/aws?ref=<tag>"
  # ... inputs ...
}

注意：按系统约定，git clone 仓库地址为 git clone 使用 https://gitcode.com/GitHub_Trending/li/litellm 后，模块 source 可按实际仓库相对位置替换为 ./terraform/litellm/aws 等本地路径。

两朵云的资源拓扑与路径路由

AWS 栈资源清单

AWS 模块对应实现文件分布在 terraform/litellm/aws（network.tf、rds.tf、redis.tf、s3.tf、secrets.tf、iam.tf、ecs.tf、alb.tf、migrations.tf 等），部署对象包括：

• 跨指定可用区的公网 + 私网子网的 VPC、一个 NAT 网关（传入既有 vpc_id 时跳过）；
• Aurora Postgres：1 writer + 1 reader，开启 IAM 数据库认证（create_database = false 时跳过）；
• ElastiCache Redis：私有、multi-AZ 故障转移、静态与传输加密，用于缓存与限流（create_redis = false 时跳过）；
• S3 bucket：私有、带版本、SSE-S3，以 S3_BUCKET_NAME / S3_REGION_NAME 暴露给 gateway / backend，用作缓存后端、请求日志归档、/v1/files 存储；
• Secrets Manager：存放自动生成的 LITELLM_MASTER_KEY（sk-…）与 Aurora 主口令（仅引导阶段使用）；
• ECS Fargate 集群运行 gateway、backend、ui 三个服务；
• Application Load Balancer（公网 HTTP/80）按路径路由；
• 一次性迁移任务 litellm-migrations。

架构示意如下（阅读原文 ASCII 图见 terraform/litellm/README.md）：

                        ┌───────────────────────────────────────┐
                        │            Public Internet            │
                        └─────────────────┬─────────────────────┘
                                          │ HTTP/80
                          ┌───────────────▼───────────────┐
                          │   Application Load Balancer   │
                          │   (path-routing listener)     │
                          └─┬─────────────┬─────────────┬─┘
                            │             │             │
            UI assets, /    │  /v1/chat,  │   /key/*    │
            /_next/*, …     │  /v1/embed, │   /user/*   │
                            │  …          │   …         │
              ┌─────────────▼───┐  ┌──────▼──────┐  ┌───▼──────────────┐
              │    ECS Service  │  │ ECS Service │  │   ECS Service    │
              │       (ui)      │  │  (gateway)  │  │    (backend)     │
              │   Fargate :3000 │  │ Fargate:4000│  │  Fargate :4001   │
              └─────────────────┘  └──────┬──────┘  └────────┬─────────┘
                                          │                  │
              ┌─── private subnets (one per AZ) ──────────────────────┐
              │   Aurora Postgres（writer+reader, IAM auth）、       │
              │   ElastiCache Redis (1 node)、版本化 S3 bucket、      │
              │   Secrets Manager（master key / DB 口令 / 用户 API key）│
              └───────────────────────────────────────────────────────┘
                          │ NAT gateway in one public subnet
                          ▼
                    egress to LLM providers

GCP 栈资源清单

GCP 模块实现见 terraform/litellm/gcp（network.tf、cloudsql.tf、redis.tf、gcs.tf、secrets.tf、iam.tf、cloudrun.tf、load_balancer.tf），部署对象包括：

• VPC + Private Services Access 网段 + Serverless VPC Access connector（让 Cloud Run 能访问私网 IP）；
• Cloud SQL for PostgreSQL：主实例 + 跨可用区只读副本，口令认证经 Secret Manager 注入；
• Memorystore (Redis)：私有 IP、传输加密 SERVER_AUTHENTICATION，供缓存与限流；
• GCS bucket：私有、版本化、uniform IAM，暴露为 GCS_BUCKET_NAME；
• Secret Manager：LITELLM_MASTER_KEY 与 DATABASE_PASSWORD；
• Cloud Run v2 服务：gateway（4000）、backend（4001）、ui（3000），共享运行服务账号；
• Cloud Run Job litellm-migrations：运行 prisma migrate；
• External HTTPS LB：serverless NEG + URL map，镜像 helm ingress 路径路由。

                        ┌───────────────────────────────────────┐
                        │            Public Internet            │
                        └─────────────────┬─────────────────────┘
                                          │ HTTP/80
                          ┌───────────────▼───────────────┐
                          │ External HTTPS Load Balancer  │
                          │   (global, URL map routing)   │
                          └─┬─────────────┬─────────────┬─┘
              ┌─────────────▼───┐  ┌──────▼──────┐  ┌───▼──────────────┐
              │   Cloud Run     │  │  Cloud Run  │  │    Cloud Run     │
              │      (ui)       │  │  (gateway)  │  │    (backend)     │
              │      :3000      │  │   :4000     │  │      :4001       │
              └─────────────────┘  └──────┬──────┘  └────────┬─────────┘
                                          │ Serverless VPC Access connector
              ┌─── VPC (private services access range) ──────────────────┐
              │   Cloud SQL Postgres（writer+reader）、Memorystore Redis、│
              │   版本化 GCS bucket、Secret Manager（口令/API key）        │
              └──────────────────────────────────────────────────────────┘

负载均衡的路径路由规则

两栈的 LB 路径前缀清单逐字镜像了 gateway/routes/allowlist.py（AWS 侧见 terraform/litellm/aws/locals.tf，GCP 侧 URL map 见 terraform/litellm/gcp/load_balancer.tf），路由规则为：

• LLM 数据面前缀 → gateway：例如 /v1/chat/、/chat/、/v1/embeddings、/v1/completions、/v1/responses、/v1/messages、/v1/batches、/v1/audio/、/v1/images/、/v1/files、/rerank、/v1/realtime、provider passthrough 前缀（/anthropic/、/bedrock/、/vertex_ai/…）、/v1beta/、/health、/metrics 等；
• UI 静态资源路径 → ui：/、/litellm-asset-prefix/*、/_next/*、/favicon.ico 等；
• 其余全部 → backend：管理面 /key/*、/user/*、/team/*、/model/* 等。

从源码角度理解这一拆分的价值：gateway/main.py 中 _is_gateway_route 会在应用启动后按 allowlist 过滤 FastAPI 路由，只保留数据面。文中明确解释了为什么用显式枚举的版本化前缀而不是笼统的 /v1/ / /v2/：宽泛前缀会误伤 /v1/access_group、/v2/key/info 等管理路由。Terraform 栈在 LB 层做同样的划分，保证管理/UI 端点不与 LLM 数据面共处同一容器，各自独立扩缩容。

配置代理：proxy_config 与每组件 env / secrets

两栈都提供三层配置通道，从上到下对应关系一致。

proxy_config（推荐方式）

它镜像 helm chart 的 gateway.config.proxy_config。AWS 侧把该 map YAML 编码后上传到 S3（bucket 内 config/litellm-config.yaml），gateway / backend 启动时经 boto3 下载到 /tmp/litellm-config.yaml 并设置 CONFIG_FILE_PATH；S3 对象 etag 被写进 task definition，因此改动 proxy_config 会自动产生新 task-def 版本并滚动重启两个服务。GCP 侧则把 YAML 上传到 GCS 桶并通过 Cloud Run v2 gcsfuse 卷只读挂载到 /etc/litellm，用 YAML 哈希作为 env 强制触发新 revision。AWS 版示例：

proxy_config = {
  model_list = [
    {
      model_name = "gpt-4o"
      litellm_params = {
        model   = "openai/gpt-4o"
        api_key = "os.environ/OPENAI_API_KEY"
      }
    },
  ]
  general_settings = {
    master_key   = "os.environ/LITELLM_MASTER_KEY"
    database_url = "os.environ/DATABASE_URL"
  }
}

LiteLLM 会针对容器环境解析 YAML 中的 os.environ/<NAME> 引用（os.environ/OPENAI_API_KEY 读取名为 OPENAI_API_KEY 的环境变量）。这意味着 provider API key 应放在 *_extra_secrets 中，YAML 里只按环境变量名引用。更完整的双模型示例（含 claude-sonnet-4-6 与 coordination_redis 注释块）见 terraform/litellm/aws/examples/default/terraform.tfvars.example 与 GCP 同路径文件。

普通环境变量（非敏感）

直接落进 ECS task def / Cloud Run service spec：

gateway_extra_env = {
  LANGFUSE_HOST = "https://us.cloud.langfuse.com"
}
backend_extra_env = {
  STORE_MODEL_IN_DB = "True"
}

tfvars.example 还给出常见后端调优项：SSO 登录重定向 AUTO_REDIRECT_UI_LOGIN_TO_SSO、文档品牌 DOCS_TITLE、UI 管理员名 UI_USERNAME。UI 登录口令是独立的一等变量 ui_password。

敏感值（API key / secrets）

AWS 要求指向已存在的 Secrets Manager secret，按 ARN 引用：

gateway_extra_secrets = {
  OPENAI_API_KEY    = "arn:aws:secretsmanager:us-west-2:111122223333:secret:openai-api-key-AbCdEf"
  ANTHROPIC_API_KEY = "arn:aws:secretsmanager:us-west-2:111122223333:secret:anthropic-api-key-GhIjKl"
}

底层行为是：执行角色自动获得每个 ARN 的 secretsmanager:GetSecretValue 权限；ECS 在任务启动时解析 secret 并把值注入左侧同名环境变量。若要从 JSON secret 中抽取单字段，用 ECS 的 :fieldName:: 后缀（如 arn:…:secret:provider-keys-AbCdEf:openai_api_key::）。创建 secret 的命令：

aws secretsmanager create-secret \
  --name openai-api-key \
  --secret-string "sk-proj-..."

GCP 侧先创建 secret 再引用其资源 ID：

echo -n "sk-proj-..." | gcloud secrets create openai-api-key --data-file=-

gateway_extra_secrets = {
  OPENAI_API_KEY = "projects/my-gcp-project/secrets/openai-api-key"
}

Cloud Run 运行 SA 自动获得这些 secret 的 roles/secretmanager.secretAccessor。特别注意 GCP README 的警告：只传裸 secret 资源 ID（projects/.../secrets/openai-api-key），绝不能带版本后缀（/versions/3），因为 secret_key_ref 绑定与 IAM 授权都拒绝版本后缀，版本始终取 latest；确需锁定版本时需直接编辑 terraform/litellm/gcp/cloudrun.tf 中 local.gateway_extra_secret_kv 设置 version = "3"。

双栈功能对等与运行语义

特性对照表

两个模块暴露同一套概念面，具体输入只在底层云差异处不同（AWS 输入见 terraform/litellm/aws/variables.tf，GCP 见 terraform/litellm/gcp/variables.tf）：

能力	AWS 输入	GCP 输入
租户 + 环境命名	tenant, env	tenant, env
Master key / 许可证	litellm_master_key, litellm_license	litellm_master_key, litellm_license
UI 管理口令	ui_password	ui_password
每部署标签	tags (map(string))	labels (map(string))
TLS 姿态	acm_certificate_arn, allow_plaintext_alb	lb_domains, allow_plaintext_lb
对象存储强制销毁	s3_force_destroy	gcs_force_destroy
数据库删除保护	skip_final_snapshot	cloudsql_deletion_protection
proxy_config（类型化 YAML map）	proxy_config	proxy_config
协调 Redis	REDIS_*（ElastiCache 自动导出）	REDIS_*（Memorystore 自动导出）
每组件普通 env	gateway_extra_env, backend_extra_env	同左
每组件 secret env	gateway_extra_secrets, backend_extra_secrets（ARN）	同左（资源 ID）
gateway 的 uvicorn --workers	gateway_num_workers	gateway_num_workers
OpenTelemetry v2（opt-in）	otel_endpoint / otel_exporter / otel_environment_name / otel_capture_message_content / otel_headers_secret_arn	同左但末项为 otel_headers_secret

每个模块会给所有可打标签的资源盖上自己的栈身份标签（AWS 用 litellm:stack，GCP 因标签键禁冒号而用 litellm-stack）+ managed-by = "terraform"，再叠加 var.tags / var.labels；AWS 上 provider 的 default_tags 最后覆盖。

协调 Redis 与缓存的区别

两栈都会托管托管 Redis（AWS ElastiCache / GCP Memorystore）并把 REDIS_HOST、REDIS_PORT、REDIS_SSL（GCP 另加 REDIS_SSL_CA_CERTS）导出进 gateway / backend 环境。代理会回退到这些变量构建协调 Redis，用于跨 Pod 的 tpm/rpm 限流、spend 追踪与 Pod 锁管理器。这与 LLM 响应缓存相互独立：除非在 proxy_config 中启用 litellm_settings.cache，否则响应缓存保持关闭。

若要改用模块未托管的 Redis，就在 var.proxy_config 中显式设置 general_settings.coordination_redis——显式配置优先于 REDIS_* 环境变量回退。注释示例位于各栈 terraform.tfvars.example：协调 Redis 支持普通模式、集群模式（startup_nodes）与哨兵模式（sentinel_nodes + service_name）。

GCP 的 Memorystore 开启 SERVER_AUTHENTICATION 传输加密后以 rediss:// 连接，实例自签 CA 证书会以 REDIS_CA_PEM_B64 下发，入口脚本解码到 /tmp/redis-ca.pem 并指向 REDIS_SSL_CA_CERTS。

OpenTelemetry v2：以 otel_endpoint 一键闸门

OTel 在两朵云上都是 opt-in，完全由 otel_endpoint 控制：留空则容器环境里不出现任何 OTel 相关内容；设置后 gateway 与 backend 都会获得 LITELLM_OTEL_V2=true 与完整 OTEL_* 块，OTEL_SERVICE_NAME 按组件打标（<tenant>-litellm-<env>-gateway 与 -backend）。gateway_extra_env / backend_extra_env 中任何 OTEL_* 键对该服务生效（GCP 上因 Cloud Run 拒绝重复环境变量名，覆盖行为可预期）。

otel_endpoint         = "http://otel-collector.internal:4318"
otel_exporter         = "otlp_http"   # otlp_grpc, console
otel_environment_name = "prod"        # defaults to var.env

需要认证头的收集器，把逗号分隔的 key=value 串存进 Secrets Manager（AWS 经 otel_headers_secret_arn，GCP 经 otel_headers_secret，如 Authorization=Bearer <token>）。内容捕获默认 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT = no_content，必须审计后端落盘内容后才可翻到 otel_capture_message_content = "prompt_and_completion"——prompt/completion 通常是敏感数据。Arize、Phoenix、Langfuse OTel、Weave、Langtrace、Levo、AgentOps 等厂商预设属于 proxy_config.litellm_settings.callbacks 范畴，与 OTLP 变量相互正交，凭据仍放 *_extra_secrets。

数据库认证：AWS IAM token 与 GCP 口令

两朵云在数据库认证上刻意不同，README 做了明确取舍：

• AWS（Aurora + IAM auth）：集群开启 iam_database_authentication_enabled 后，还需一次性执行 CREATE USER ... GRANT rds_iam。bootstrap.tf 通过一次性 Fargate 任务（postgres:16-alpine 用 Secrets Manager 中的主口令执行幂等 SQL）在 apply 期间自动完成。运行时代理由离散的 DATABASE_HOST/PORT/USER/NAME 拼出 DATABASE_URL 并附加短时 IAM token，实现在 litellm/proxy/auth/rds_iam_token.py（任务角色带限定到该 IAM 用户 + 集群的 rds-db:connect）。
• GCP（Cloud SQL + 口令）：LiteLLM 的 init_iam_db_url_from_env() 只通过 boto3 签发 AWS RDS token，不讲 GCP IAM 方言；要在 Cloud Run 中对 Cloud SQL 做 IAM 认证得引入 cloud-sql-proxy 边车（Cloud Run v2 支持多容器），会复杂化服务规格。因此 GCP 栈走口令认证：随机口令入 Secret Manager，每个 Cloud Run 服务以 secret_key_ref 方式拿到 DATABASE_PASSWORD，入口 shim 在 exec uvicorn 前拼出 DATABASE_URL（与 DATABASE_URL_READ_REPLICA），口令不会出现在 service spec 或日志里。相关能力在 gateway/main.py 也有对应：DatabaseURLSettings.from_env().apply_to_env() 会按 IAM 或口令两种模式装配数据库 URL。

数据面与迁移的启动顺序

LiteLLM proxy 在启动时会跑 prisma migrate deploy，但首次 apply 时 gateway/backend 可能撞上空库竞态，因此两个栈都提供一次性迁移任务执行 litellm/proxy/prisma_migration.py（对 backend 镜像运行 python litellm/proxy/prisma_migration.py）：

• AWS：aws_ecs_task_definition（litellm-migrations），用 aws ecs run-task 执行，完整命令打印在 terraform output；
• GCP：google_cloud_run_v2_job（litellm-migrations），用 gcloud run jobs execute 执行。

在首次 terraform apply 之后、gateway/backend 服务开始对外服务之前运行一次迁移任务。 实际应用中 AWS 的 apply 会通过 local-exec 自动执行引导与迁移，且 gateway/backend 服务 depends_on 迁移任务，保证 schema 就绪后才拉起（见 terraform/litellm/aws/README.md 的 "Aurora + IAM auth" 一节）。运行 terraform 的机器必须装好并认证 aws / gcloud CLI。

TLS 与数据保留：两个安全默认值

AWS TLS：terraform plan 默认拒绝部署纯 HTTP ALB。生产路径是先在 var.region 创建/导入 ACM 证书覆盖将指向 ALB 的 DNS 名，再设 acm_certificate_arn；结果 443 监听器承载路径路由，80 监听器对 HTTP 做 301 永久跳转。试用路径显式设 allow_plaintext_alb = true，否则 plan 会因前置条件失败并给出清晰报错。

GCP TLS：同样默认拒绝纯 HTTP LB。因托管证书需要 DNS 已指向 LB 的 anycast IP 存在先有鸡还是先有蛋的问题，GCP README 给出三步入径：先用 allow_plaintext_lb = true 应用一次读取 terraform output -raw lb_ip → 把域名 A 记录指向该 IP → 设置 lb_domains = ["proxy.example.com"] 并移除 allow_plaintext_lb 重新 apply。托管证书首次可能停在 PROVISIONING 15~60 分钟等待 DNS 生效，用 gcloud compute ssl-certificates describe <tenant>-litellm-<env>-cert 观察状态。

数据保留：两栈都有防误删开关。AWS 默认 skip_final_snapshot = false（销毁前先打 <cluster>-final-<short-sha> 快照）、s3_force_destroy = false（非空桶拒绝销毁）；GCP 默认 cloudsql_deletion_protection = true（拒绝销毁数据库）、gcs_force_destroy = false。这些只对模块自己创建的资源生效，自带数据库的销毁生命周期与谁创建谁负责。只有可接受丢数据的临时/CI 栈才应翻转。

多租户：命名约定与单配置多栈

所有资源命名遵循 ${tenant}-litellm-${env}（外加资源后缀），因此同账号/同项目内只要 (tenant, env) 不同就能共存：

tenant	env	示例资源名
acme	stage	acme-litellm-stage-gateway
acme	prod	acme-litellm-prod-master-key
globex	dev	globex-litellm-dev-license

按租户独立部署时仅需变化租户 slug、env 与两份预签发 secret。两个 secrets 都可选：省略 litellm_master_key 时自动生成随机 sk-…（试用/开发路径）；省略 litellm_license 时不建 license secret，gateway/backend 以 OSS 模式运行。文档特别建议用 TF_VAR_* 环境变量而非 tfvars 文件传这两个值——写进 tfvars 的值会落进 terraform.tfstate 和被提交的示例文件。

在一份配置里跑多个租户时，AWS 侧可直接用 for_each（无 provider 块因此可行）：

module "litellm" {
  for_each = toset(["acme", "globex"])
  source   = "github.com/BerriAI/litellm//terraform/litellm/aws?ref=<tag>"
  tenant   = each.key
  env      = "prod"
  region   = "us-west-2"
  azs      = ["us-west-2a", "us-west-2b"]
}

GCP 侧有重要限制：模块 versions.tf 声明的 google / google-beta 不带 configuration_aliases，只会接收调用方唯一的默认（无 alias）provider——这保持了单命令路径的简洁，但 for_each 的所有实例都跑在同一个 project、region、credentials 上，只能用于同一项目内多租户，无法自行跨项目/区域扇出；要跨项目需每项目一份根配置或 fork 模块加 configuration_aliases 后逐实例传 providers = { ... }。

快速开始：example 根模块实战

terraform/litellm/aws/examples/default 是配置好 aws provider 并调用模块的薄根（provider 可选 default_tags 槽位给组织级标签），AWS 快速开始：

cd terraform/litellm/aws/examples/default
cp terraform.tfvars.example terraform.tfvars
# Edit: region, tenant, env, azs, proxy_config, gateway_extra_secrets.

terraform init
terraform apply

一次 apply 完成全部资源创建、DB 用户引导、schema 迁移，然后才拉起 gateway/backend 服务，返回时即对外服务。取用入口：

terraform output alb_url
# UI 登录：admin / <master key>
aws secretsmanager get-secret-value \
  --secret-id "$(terraform output -raw master_key_secret_arn)" \
  --query SecretString --output text

GCP 侧路径一致（terraform/litellm/gcp/examples/default），编辑项换成 project, region, tenant, env, image_registry, proxy_config, gateway_extra_secrets；输出用 terraform output lb_url，master key 用 gcloud secrets versions access latest --secret="$(terraform output -raw master_key_secret_id)"。前提是 gcloud 已认证且启用 run / sqladmin / redis / secretmanager / vpcaccess / compute / servicenetworking / storage / artifactregistry 等 API。

两个 examples/default/ 都是薄根，只暴露精选变量面；进阶旋钮（按组件 CPU/内存/workers/实例数、自动扩缩容、RDS/Redis 规格、按组件镜像 pin）需直接设置在 module "litellm" 块上，或按上文模块用法自行组织根配置。

作为模块消费：示例根 + assume-role

provider "aws" {
  region = "us-west-2"
  assume_role { role_arn = "arn:aws:iam::111122223333:role/deployer" }
}

module "litellm" {
  source = "github.com/BerriAI/litellm//terraform/litellm/aws?ref=<tag>"

  region = "us-west-2"
  tenant = "acme"
  env    = "prod"
  azs    = ["us-west-2a", "us-west-2b"]
  # ...any of the inputs in variables.tf...
}

GCP 版需同时声明 google 与 google-beta provider（模块经调用自动继承两者）。模块标签策略：AWS 模块把自身 litellm:stack / managed-by / var.tags 盖到每个可标记资源，provider default_tags 最后叠加——组织级标签放 provider，部署级标签放 tags 输入；GCP 与之对应使用 labels。

两栈镜像拉取策略与 GCP 必读警告

AWS 默认镜像 ghcr.io/berriai/litellm-<component> 匿名可读，四个镜像（gateway / backend / ui / migrations）随 LiteLLM 版本一起升级。执行角色自带 AmazonECSTaskExecutionRolePolicy，同账号 ECR 直接可拉；跨账号 ECR 需附加 ecr:GetAuthorizationToken + ecr:BatchGetImage 策略；GHCR PAT / Docker Hub 等其他私有仓库则在 Secrets Manager 里放 {"auths":{...}} Docker 配置并给 task def 配 repositoryCredentials.credentialsParameter。

GCP 有一个强制要求：Cloud Run 只接受 Artifact Registry、[region.]gcr.io 或 docker.io 的镜像，默认 image_registry = ghcr.io/berriai 会在 apply 时被拒——所以包括 HCP 一键部署在内的每次真实部署都必须提供镜像来源。一次性设置（每项目一次）创建指向 GHCR 的 remote 仓库：

gcloud artifacts repositories create litellm \
  --repository-format=docker \
  --location=us-central1 \
  --mode=remote-repository \
  --remote-repo-config-desc="GitHub Container Registry passthrough" \
  --remote-docker-repo=https://ghcr.io

再指向它：

image_registry = "us-central1-docker.pkg.dev/my-gcp-project/litellm/berriai"
image_tag      = "v1.86.0-dev"

四个 litellm-<component>:${image_tag} URI 由这两个变量拼出；需要按组件覆盖才单独设 gateway_image / backend_image / ui_image / migrations_image。运行 SA 不需要 roles/artifactregistry.reader——Cloud Run 用项目的 serverless agent 拉取镜像。完全隔离网络的环境则手动镜像到普通 AR 仓库（docker pull → docker tag → docker push 循环，见 terraform/litellm/gcp/README.md 的 "Image pulls"），此时 image_registry 去掉 /berriai 组织段。

HCP Terraform no-code：1-click 部署与遗留手工步骤

两个栈都可作为 HCP Terraform 私有仓库的 no-code 模块发布。终端用户流程：打开 no-code 启动链接 → 填少量输入 → 点 Create workspace，HCP 用变量集凭据（静态 key 或 OIDC 动态凭据）对云账号执行 plan/apply。

启动器必须补给的覆盖项：

• AWS（terraform/litellm/aws）：region、azs、tenant、env。镜像变量可留默认——GHCR 镜像匿名可读，ECS Fargate 无需额外凭据即可拉取。
• GCP（terraform/litellm/gcp）：project、tenant、env，以及二选一——image_registry 指向由 https://ghcr.io 支撑的 AR remote 仓库（如 us-central1-docker.pkg.dev/<project>/litellm/berriai），或四个 *_image URI 全部指向已镜像进普通 AR 仓库的镜像。原因同上：默认 ghcr.io/berriai 会被 Cloud Run 准入拒绝。

无论是否用 HCP no-code，仍留手工步骤的是一次性迁移任务：栈本会在 apply 期间通过 local-exec 自动执行，但这要求 runner 装有 aws / gcloud CLI，而 HCP 托管的 runner 没有——要么用带相关 CLI 的自定义镜像的 HCP agent pool，要么在首次 apply 后手动运行 migration_run_command 输出打印的命令。

文档明确不覆盖的部分

• TLS 证书 / 自定义域名：两栈默认提供纯 HTTP LB，ACM 证书（AWS）或 Google 托管证书（GCP）需自行接入 LB；
• 远端 state 后端：默认本地 state，团队化时在 versions.tf 里补 s3 / gcs backend 块；
• 云厂商默认之外的观测能力：AWS 侧 CloudWatch Logs、GCP 侧 Cloud Logging 之外的 Prometheus / Datadog / Langfuse 等，要么经 *_extra_env 接入，要么启用 OTel v2。

此外，各模块的变量全集、按文件的功能划分（network.tf、ecs.tf、cloudrun.tf、load_balancer.tf 等各自职责）分别在 terraform/litellm/aws/README.md 与 terraform/litellm/gcp/README.md 的 "Files" 表格中逐文件列出，可与上述架构说明互相印证；GCP 侧还有可交互式向导部署的 terraform/litellm/gcp/examples/default/TUTORIAL.md 与 deploystack.json 供 Cloud Shell 一键体验。