[Anna Wiewer-MSFT (annawiewer)]

Summary

Add a Terraform reference sample for AI Gateway and Microsoft Foundry under
samples/terraform, with a catalog entry and credential-free offline CI.

• Two network end states: Public and Private-only. The private-connectivity
  profile is an intermediate provisioning stage, not a third end state.
• API-key access and additive Microsoft Entra ID caller authorization, separate
  from the gateway's managed identity for Foundry model access.
• Optional private hosted-agent infrastructure. The application/image deployment
  and actual runtime identity binding remain separate steps.
• Adjacent README/deployment guide, two architecture diagrams, guarded acceptance
  helpers, and regression tests.

Maintainer decisions requested before marking ready

Legacy preview resource contract: this sample deliberately uses
Microsoft.ApiManagement/service@2025-09-01-preview, SKU AIGateway, rather than
the newer Microsoft.ApiManagement/aigateways resource. The reason is the private
endpoint scenario: the newer resource lacks private endpoints according to the
current documentation reviewed on October 25, 2026.

Microsoft's resource lifecycle guidance
requires migration before January 15, 2027 and documents restrictions on new
legacy-resource creation. The sample is therefore a time-limited preview
reference, not a generally available new-deployment or production promise.
Earlier successful reference deployments do not override the documented support
and availability limits. This PR does not implement migration.

Please confirm whether this legacy/private-endpoint reference is appropriate for
this repository before the draft is promoted to ready for review.

Sample placement: the existing catalog currently links to external sample
repositories. This proposal adds an in-tree Terraform sample and changes the
catalog description accordingly. Please confirm whether in-tree hosting is
preferred over placement in a separate Azure-Samples repository.

Implementation and scope

The sample uses Microsoft's existing Azure/azapi provider with explicit ARM
types/API versions and Terraform-managed dependencies and state. It does not
introduce a custom provider or claim to be an official Terraform Registry module.
Some preview child resources require selective local schema-validation opt-outs;
Azure API validation, authorization and Azure Policy are not bypassed.

The diff is based directly on upstream main at
db053fe3c45389eb2b993fd6c3fd0617612b8936 and contains only:

• samples/terraform/**
• An additive entry and corresponding description update in samples/README.md;
  existing Bicep and external sample links are preserved.
• .github/workflows/terraform-offline.yml, with read-only repository
  permissions, pinned actions and no Azure credentials.

No plugin/CLI changes, root README changes, .gitignore changes, fork history,
environment-specific inputs, Terraform state, keys or operational evidence are
included.

Validation

Executed the existing runner in a fresh, isolated worktree of this PR candidate:

.\samples\terraform\scripts\Test-Offline.ps1

• Terraform initialization with the committed lockfile, formatting and validation passed.
• 26 mocked Terraform plan tests passed.
• 5 Python tests passed.
• 20 model-script cases, 58 customer-acceptance scenarios and 14 portal-evidence
  cases passed.
• PowerShell scripts parsed successfully.

This is local validation of the PR candidate, not an upstream CI result.
No Azure deployment, model inference, browser acceptance or paid live operation
was performed while preparing this PR.

The documentation separately records earlier bounded reference runs, including
private model/agent inference and managed-identity Entra allow/deny behavior.
Those observations are not a new clean-subscription deployment guarantee.
Private-from-first-create where temporary public access is prohibited, custom
delegated-user clients and migration to the newer resource remain outside the
claimed proof.

Operational boundaries

Existing private deployments must retain their original state, complete inputs
and final network profile; the runbook does not reopen public endpoints to bypass
failures. Resource deletion guards, scoped runtime roles, plan review and
acceptance gates remain in place.

The preview has no SLA. Supporting services and model calls incur charges;
offline checks do not certify service availability, policy compatibility,
private routing or production readiness.

[Anna Wiewer-MSFT (annawiewer)]

@microsoft-github-policy-service agree company="Microsoft"

[Anna Wiewer-MSFT (annawiewer)]

Paul Yuknewicz (@paulyuk) Could you advise whether this legacy-preview Terraform sample is appropriate for this repository, and whether you prefer in-tree or external Azure-Samples hosting? Keeping this as a draft pending that direction.