docs(spec): private registry connections for hosted agents

[Wei Meng (m5i-work)]

Resolves #9582

Summary

Doc-only PR. Adds docs/specs/foundry-private-registry/spec.md, a technical design spec for deploying Foundry hosted agents from private non-ACR images through a Foundry project connection. No product code changes — the workflows are target behavior whose availability on main is tracked separately by #9588 and #9586.

The service contract is defined by the merged Foundry REST API specification, based on the service team's internal Vienna design. The azd design remains registry-neutral: JFrog is the first E2E target, not a production-code dependency or allowlisted vendor.

What the spec covers

• Agent authoring and REST mapping — registryConnectionId maps to definition.container_configuration.registry_connection_id.
• Explicit image passthrough — top-level image plus docker.imagePassthrough: true; no build, pull, copy, login, or push.
• Greenfield agent scenario — start from an existing Foundry project and a connection created beforehand through the Foundry portal or Azure CLI, initialize with --registry-connection, and deploy without a post-init provision step.
• Brownfield agent scenario — adopt an existing Foundry project, provision a sibling host: azure.ai.connection service, and then deploy the dependent agent.
• Lifecycle ownership — core handles passthrough Package/Publish artifacts; the agents extension handles authoring, dependency validation, connection lookup, and Foundry request mapping.
• Validation boundaries — azd validates authoring and dependencies while Foundry and the registry remain authoritative for vendor support, token exchange, trust, and image-pull authorization.
• Security and compatibility — no registry credentials enter the agent payload; older pre-built-image projects retain their compatibility fallback.

Relationship to implementation work

Foundry service API contract                    Azure/azure-rest-api-specs#44915
└─ core container image passthrough             Azure/azure-dev#9588
   └─ agents private-registry connection        Azure/azure-dev#9586

This docs PR is independent and targets main; it does not participate in the implementation PR stack.

Out of scope

Vendor-specific production behavior, registry setup wizards, registry-side OIDC/identity configuration, Entra audience application creation, static pull-secret support, non-ACR remote builds, and a first-class registry connection category are explicitly excluded.

Validation

git diff --check
cspell lint "docs/specs/foundry-private-registry/spec.md" \
  --config ./.vscode/cspell.misc.yaml --no-progress

[azure-pipelines]

Azure Pipelines:
7 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Pull request overview

Adds a technical design for private non-ACR images used by Foundry hosted agents.

Changes:

• Defines registry-connection authoring and REST mapping.
• Documents imperative and declarative workflows.
• Specifies lifecycle, validation, security, compatibility, and testing boundaries.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (1)

docs/specs/foundry-private-registry/spec.md:301

• The linked core implementation does not actually validate container-image syntax here: it calls the existing docker.ParseContainerImage, which accepts invalid references such as https://registry.example.com/repo. This makes the documented lifecycle and the issue's syntactically-valid-image boundary inaccurate for declarative azure.yaml input. Either strengthen #9588 with a standards-compliant reference validator or explicitly document the limited parse check and defer syntax validation to Foundry. [azd-code-reviewer]

Core recognizes `docker.imagePassthrough: true`, validates the image reference, and returns without a local or remote build. Docker is not required. `docker.remoteBuild` is neither generated nor permitted with image passthrough.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (1)

docs/specs/foundry-private-registry/spec.md:424

• The identity-mapping URL currently returns 404, so this reference cannot guide readers to the stated setup API. Link to JFrog's live OpenID Connect integration documentation instead.

- [JFrog OIDC configuration API](https://docs.jfrog.com/administration/reference/createoidcconfiguration) and [identity mapping API](https://docs.jfrog.com/administration/reference/createoidcidentitymapping) — vendor setup references for the JFrog end-to-end example only.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (2)

docs/specs/foundry-private-registry/spec.md:257

• azd-code-reviewer: These angle-bracket placeholders are shell redirection operators when left unquoted, so the setup block fails before azd env set can run. Quote every placeholder-bearing value in this block.

azd env set AZURE_AI_PROJECT_ID <foundry-project-resource-id>

# Generic connection and image configuration.
azd env set REGISTRY_URL https://<private-registry-host>
azd env set REGISTRY_AUDIENCE <entra-audience-app-id>

docs/specs/foundry-private-registry/spec.md:145

• azd-code-reviewer: The angle-bracket image placeholder is parsed by shells as input/output redirection, so this command fails before azd runs. Quote the placeholder-bearing image argument, as the project placeholder above already is.

This issue also appears on line 253 of the same file.

  --image <private-registry-host>/<repository>/agent:<tag> \

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (2)

docs/specs/foundry-private-registry/spec.md:251

• [azd-code-reviewer] The angle-bracket values throughout this shell block are unquoted, so shells interpret <...> as redirections instead of arguments and the example cannot be followed as written. Quote each placeholder-bearing value.

azd env set AZURE_AI_PROJECT_ID <foundry-project-resource-id>

docs/specs/foundry-private-registry/spec.md:145

• [azd-code-reviewer] This unquoted angle-bracket placeholder is parsed by POSIX shells as input/output redirection, so copying the documented command fails before azd receives the image. Quote the placeholder value.

This issue also appears on line 251 of the same file.

  --image <private-registry-host>/<repository>/agent:<tag> \