From 184d1c96626ccbbb37775079c4428c84fed46b81 Mon Sep 17 00:00:00 2001
From: cunninger <1803912219@qq.com>
Date: Sun, 23 Aug 2026 11:22:58 +0800
Subject: [PATCH] docs(gcp): document OS Config metadata for VPC connector

---
 terraform/litellm/gcp/README.md               | 19 +++++++++++++++++++
 .../litellm/gcp/examples/default/TUTORIAL.md  | 17 +++++++++++++++++
 terraform/litellm/gcp/network.tf              |  5 +++++
 3 files changed, 41 insertions(+)

diff --git a/terraform/litellm/gcp/README.md b/terraform/litellm/gcp/README.md
index 88e9979148f..b4c8a719d88 100644
--- a/terraform/litellm/gcp/README.md
+++ b/terraform/litellm/gcp/README.md
@@ -315,6 +315,25 @@ The `migration_run_command` output is preserved for break-glass manual re-runs.
 required APIs must be enabled (run, sqladmin, redis, secretmanager,
 vpcaccess, compute, servicenetworking, storage, artifactregistry).
 
+If the organization enforces
+`constraints/compute.managed.requireOsConfig`, existing projects also
+need VM Manager (OS Config) enabled in project metadata before apply.
+The Serverless VPC Access connector creates GCE VMs; without this
+metadata the connector operation fails, Terraform's error is vague,
+and Cloud operation logs report an org-policy violation. New projects
+created after the constraint is already on are usually fine. Existing
+projects are not. Set it once per project:
+
+```bash
+gcloud compute project-info add-metadata \
+  --project PROJECT_ID \
+  --metadata=enable-osconfig=TRUE
+```
+
+Do not manage this from the module: project-wide metadata is often
+owned by another Terraform root. Google's setup notes:
+https://docs.cloud.google.com/compute/vm-manager/docs/setup#set_metadata_values
+
 ## TLS
 
 `terraform plan` refuses to provision an HTTP-only LB by default — TLS
diff --git a/terraform/litellm/gcp/examples/default/TUTORIAL.md b/terraform/litellm/gcp/examples/default/TUTORIAL.md
index 5c7144619d6..4a12833ff06 100644
--- a/terraform/litellm/gcp/examples/default/TUTORIAL.md
+++ b/terraform/litellm/gcp/examples/default/TUTORIAL.md
@@ -29,6 +29,23 @@ gcloud services enable \
   artifactregistry.googleapis.com
 ```
 
+## Enable VM Manager (OS Config) on existing projects
+
+Skip this on a brand-new project created after
+`constraints/compute.managed.requireOsConfig` is already enforced.
+Existing projects that later get that org policy need this metadata, or
+`terraform apply` fails while creating the Serverless VPC Access
+connector and Terraform's error is vague. Cloud operation logs then
+report an OS Config org-policy violation.
+
+```bash
+gcloud compute project-info add-metadata \
+  --project <your-project-id> \
+  --metadata=enable-osconfig=TRUE
+```
+
+See https://docs.cloud.google.com/compute/vm-manager/docs/setup#set_metadata_values
+
 ## Create the Artifact Registry passthrough to GHCR
 
 Cloud Run only pulls from Artifact Registry, `gcr.io`, or `docker.io`; it rejects `ghcr.io` URIs at apply time. The four LiteLLM images live on GHCR, so the stack needs a remote Artifact Registry repo pointed at GHCR. This is a one-time setup per project.
diff --git a/terraform/litellm/gcp/network.tf b/terraform/litellm/gcp/network.tf
index a1ccaed02f9..0d5326e67d3 100644
--- a/terraform/litellm/gcp/network.tf
+++ b/terraform/litellm/gcp/network.tf
@@ -36,6 +36,11 @@ resource "google_service_networking_connection" "psa" {
 # machine_type alone). Defaults: 2 e2-micro instances scale up to 3 — fine
 # for low-to-moderate Cloud Run egress; bump max if your services push
 # heavy private-network traffic.
+#
+# If constraints/compute.managed.requireOsConfig is enforced, existing
+# projects need enable-osconfig=TRUE in project metadata before this
+# connector can be created. The module does not set that metadata
+# (it is often owned by another root). See README.md Quick start.
 resource "google_vpc_access_connector" "this" {
   name          = "${local.name}-conn"
   region        = var.region