Stabilize container registry model APIs (ASPIRECOMPUTE003) for 17.1 #22163

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

Track the requested 17.1 stabilization of the container registry model (ASPIRECOMPUTE003) while retaining its functionality. This is a stabilization/design work item, not a newly reproduced runtime defect and not approval to remove the APIs or blanket-remove experimental attributes.

The diagnostic currently spans user-facing entry points and lower-level model/extension contracts. These need a split API review before graduation. The historical audit recommendation was Split / review, not approval to stabilize every contract together.

Verified against current main at 793dfe6e254fe050af24cb7bcfba214066dcaab8:

Source: entry points and dispatcher, resource, default-target annotation.

Expected Behavior

Graduate the reviewed user-facing registry contracts to stable, preserving registry registration, explicit selection and image publication. Consider graduating those contracts before committing the lower-level extension plumbing, provided the resulting exposed types and generated SDK contracts are coherent.

Required planning gate before implementation:

• Review credentials across generic registries and ACR: define external-login prerequisites versus Aspire-managed login, push versus deployed-workload pull authentication, secret handling and multi-registry login ordering. The generic registry API/interface does not model credentials; ACR has a provisioning-context-dependent login step before push prerequisites. Coordinate with Add WithCredentialsLogin extension for ContainerRegistryResoure #13772 and the reported credential-concurrency defect Azure Container Registry: concurrent login steps can overwrite Docker credentials and cause unauthorized pushes #21090 rather than inventing a new credential defect here.
• Decide and document target-selection precedence and defaults. Core resolution currently prefers an explicit resource reference, then the deployment target's registry, then exactly one default-target annotation; multiple default annotations without explicit selection throw. Docker Compose selects an explicit environment registry or a sole model registry, otherwise falls back to local images; Kubernetes uses the same first two choices but returns no registry rather than a local fallback. Review repeated selection and multiple-environment scenarios without assuming these provider distinctions must be removed.
• Review supported provider combinations and publish/deploy contracts. ACA and App Service currently reject non-ACR resources through their ContainerRegistry getters; generic WithContainerRegistry is not evidence that every provider supports every registry. Coordinate external ACA registry support with Azure Container App Environment (ACA) with external container registry #14286 and property/annotation contract review with Should IAzureComputeEnvironmentResource.ContainerRegistry be obsoleted in favor of ContainerRegistryReferenceAnnotation? #18551.
• Preserve deferred endpoint/repository expressions and image naming; review remote push versus local tag-only behavior and archive output. Separate inspectable publish artifacts from deploy-time authentication/provisioning/push. Keep existing compute publication working; coordinate, but do not implicitly bundle, the image-artifact expansion in Add container image resources and registry publication independent of compute #20674.
• Resolve run-mode representation in coordination with AzureContainerRegistryResource is missing from the dashboard in run mode #21059. Generic registry creation currently deliberately omits the resource from the run model, with tests asserting that behavior. Decide the intended generic and Azure representation without provisioning or modifying an existing registry merely to display it.
• Record the approved stable subset, any contracts remaining experimental with their blockers, compatibility implications, and remaining design decisions. Validate the chosen contract with focused run/publish tests, selection/ambiguity cases, provider authentication/push coverage, generated SDK checks and updated documentation before graduation. No maintainer approval or provider-wide GA readiness is established by this work item.

Supporting implementation: core selection, push/tag behavior, ACR login, Compose selection, Kubernetes selection.

Steps To Reproduce

N/A — requested stabilization work item. Static source and existing-test inspection establishes the current marker scope and behavior; no new runtime defect or reproduction is claimed. Existing core coverage is in ContainerRegistryResourceTests.cs. No builds, tests or live provider deployments were run for this filing.

Exceptions (if any)

N/A.

Aspire doctor output

N/A — API stabilization planning, not an environment-specific failure report.

Anything else?

Requested target: 17.1, subject to maintainer prioritization; not a release commitment.

Related to #21059: that issue tracks AzureContainerRegistryResource missing from the dashboard/run graph, including AsExisting. The current Azure helper also uses CreateResourceBuilder rather than AddResource in run mode. Its visibility/lifecycle decision informs the stable registry contract, but #21059 is not itself a request to graduate ASPIRECOMPUTE003, and removing the diagnostic would not fix visibility. Keep its concrete defect tracked there.

Related broader graduation tracking: #17175. Historical audit reference: 2f471dc6f8019fc1660e1f1ea153078c99be5e85.

Requested scope is issue/planning only: no stabilization implementation, product-code changes or pull request.