Decouple Vertex model location from GCP compute region and preflight model access

What does the feature do?

Decouple the Vertex AI model-serving location from the GCP compute/deploy region, and preflight GCP model access before provisioning resources.

Today configureAccessGateway initializes VERTEXAI_LOCATION from AccountInfo.Region. Only the chat-large alias is special-cased to global; an explicit model such as gemini-3.5-flash therefore inherits the compute region.

That cannot work for every Vertex model. Gemini 3.5 Flash Standard PayGo is served at global, us, and eu, while europe-west2 and its listed Asia regions are Single Zone Provisioned Throughput only. Ordinary compute regions such as us-central1 are not serving locations for this model. A stack may reasonably run in us-central1 while its model gateway must use VERTEXAI_LOCATION=global or us.

There is a second independent gate: constraints/vertexai.allowedModels. In the project that exposed this problem, authenticated calls to global, us, and eu all failed because the effective organization policy did not allow:

publishers/google/models/gemini-3.5-flash:predict

Moving compute regions cannot fix either mismatch, and the current failure arrives only when the application calls the synthesized LiteLLM gateway.

Google references:

• Gemini 3.5 Flash locations and consumption options: https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/gemini/3-5-flash
• Model access policy: https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/control-model-access
• Organization Policy API: https://docs.cloud.google.com/organization-policy/reference/rest

What does the desired solution look like?

Treat these as two coordinated pre-deploy concerns, while keeping their security boundaries distinct.

1. Resolve model-serving location independently

For GCP managed models, synthesize VERTEXAI_LOCATION independently of the compute region.

Proposed resolution order:

1. An explicit per-model serving-location override.
2. Defang's provider/model metadata for aliases and known concrete models.
3. global for Gemini models that support global PayGo.
4. A clear pre-deploy error when Defang cannot select a supported endpoint safely; do not silently substitute another model or consumption mode.

Add a provider-specific serving-location override on the modern top-level models: entry. The implementation should choose a schema consistent with existing Compose extension conventions; conceptually:

models:
  chat:
    model: gemini-3.5-flash
    # Vertex serving location: global (default), us, or eu
    <serving-location-option>: us

global should be the default for eligible Gemini models because it provides the broadest on-demand availability. Users who require residency can explicitly select us or eu. The compute deployment can remain in a concrete region such as us-central1.

The resolved project should then contain:

--model vertex_ai/gemini-3.5-flash
VERTEXAI_LOCATION=global # or the explicit us/eu value

Do not make a blanket assumption for models that do not support the global endpoint. Keep the location decision model-aware and validate it against provider metadata where possible.

2. Preflight the effective model-access policy

Before the application/model gateway rollout becomes live, check whether the selected model/action can be used at the resolved endpoint. Some checks may need to run after initial project bootstrap enables APIs or establishes identity. Distinguish:

• unsupported serving location;
• PayGo unavailable / Provisioned Throughput only;
• vertexai.allowedModels denial;
• missing permission to inspect the effective policy;
• ordinary IAM or API enablement failures.

For an organization-policy denial, report:

• the evaluated denial and candidate allowlist value, such as publishers/google/models/gemini-3.5-flash:predict (an explicit deny or inherited rule may instead need to be changed at its owning scope);
• the effective policy and defining ancestor, when determinable with the caller's permissions;
• links/commands for the administrator to inspect and update it;
• that propagation can take up to 15 minutes.

The initial implementation should not automatically change vertexai.allowedModels during compose up or ordinary GCP bootstrap:

• it is an intentional governance boundary, not a normal service API toggle;
• it is frequently owned by a parent folder or organization;
• Defang's project bootstrap identity normally should not have roles/orgpolicy.policyAdmin;
• setting a list policy can overwrite existing rules/allowlisted models if it is not merged with etag protection;
• silently broadening model access would violate least surprise.

Policy remediation, if desired, should be designed in a separate follow-up issue as an explicit administrator workflow. It should never be an implicit side effect of deployment.

Suggested user flow

1. Load and resolve the Compose project.
2. Resolve model ID and serving location independently from compute region.
3. Validate from an authoritative provider source that the model supports PayGo at that location. Handle unknown models without silently guessing or substituting a model.
4. Check effective vertexai.allowedModels access on a best-effort basis when the API/permissions permit it.
5. Stop rollout on an unsupported model/location combination or confirmed policy denial. Warn and continue when policy inspection itself is unauthorized or unavailable; preserve the underlying Vertex error if the runtime call later fails.
6. Synthesize the gateway with the resolved values.

This keeps the common path automatic (global) while making us/eu residency explicit and preserving the cloud administrator's policy authority.

Acceptance criteria

• A GCP stack deployed in us-central1 can synthesize a Gemini 3.5 Flash gateway with VERTEXAI_LOCATION=global, us, or eu without changing the compute region.
• Eligible Gemini models default to global; the rule is model-aware and does not force unsupported models to global.
• Users can explicitly select the Vertex serving location on a modern top-level models: entry.
• The resolved configuration displays both vertex_ai/<model> and the resolved VERTEXAI_LOCATION before deployment.
• Invalid model/location and PayGo/PT-only combinations fail before cloud provisioning with an actionable error.
• A confirmed constraints/vertexai.allowedModels denial reports the evaluated reason, candidate <model>:predict allowlist value, and remediation guidance.
• Inability to read the effective organization policy warns but does not block an otherwise valid deployment.
• Ordinary compose up and GCP bootstrap do not mutate organization policy implicitly.
• Model availability comes from an authoritative, maintainable source; unknown models have explicit graceful behavior rather than a guessed endpoint.
• Tests cover default global selection, preserved explicit us/eu, compute/model location independence, never selecting global for an unsupported model, confirmed policy denial, unreadable policy, and compatibility with existing aliases including chat-large.
• Managed-model documentation explains endpoint location versus compute region and links to Google organization-policy instructions.

Implementation notes

• Current synthesis is in src/pkg/cli/compose/fixup.go (configureAccessGateway).
• GCP BYOC bootstrap currently enables project APIs and grants project IAM in src/pkg/cli/client/byoc/gcp/byoc.go; organization-policy mutation should not be folded into those broad setup side effects.
• Keep the modern top-level models: syntax. Do not extend the deprecated provider: { type: model } syntax.
• Do not silently fall back to another model.

Checklist of tasks to complete

• Implementation is complete
• Tests are written and passing
• Samples added/updated, if needed
• Documentation is updated, including policy troubleshooting
• Someone else has confirmed the feature against a restricted GCP project

Start in src/pkg/cli/compose/fixup.go at configureAccessGateway to trace current model and location synthesis, then inspect src/pkg/cli/client/byoc/gcp/byoc.go to keep bootstrap side effects separate. Review the modern top-level models: syntax and existing aliases before defining the location and policy checks. Done means the acceptance criteria are covered by tests, managed-model documentation, and actionable pre-deploy behavior without implicit organization-policy mutation.