feat: add container image passthrough

[Wei Meng (m5i-work)]

Summary

Adds an explicit core signal for service targets that deploy an already-published container image by reference:

services:
  api:
    host: containerapp
    image: registry.example.com/apps/api:1.0
    docker:
      imagePassthrough: true

When docker.imagePassthrough is true, azd treats the service-level image as the final remote container artifact and does not:

• require Docker or Podman
• build the image locally
• start an ACR Tasks remote build
• pull or tag the image
• authenticate to its registry
• copy or publish the image

The exact image reference is passed to the service target through remote package and publish artifacts.

Fixes #9587

Motivation

Core Docker framework packaging runs before extension service-target packaging. For a service with a top-level image and no local build artifact, core currently treats the image as an external source image and performs docker pull followed by docker tag.

That behavior is correct for existing Container Apps, AKS, and App Service scenarios that copy an external image into a deployment registry, but it prevents targets that delegate image retrieval to the destination platform. One example is a Foundry hosted agent whose private registry authentication is represented by a Foundry project connection rather than local Docker credentials.

The agents extension currently uses docker.remoteBuild: true to suppress local Build and Package. That is not the intended meaning of remoteBuild, which represents an ACR Tasks build.

Behavior

Passthrough

image: private.example.com/team/agent:v1
docker:
  imagePassthrough: true

Produces a remote container artifact with the same image reference during Package and Publish. Core performs no local or remote image operations.

Validation

The following combinations are rejected:

# Missing service-level image
docker:
  imagePassthrough: true

# Conflicting image lifecycles
image: private.example.com/team/agent:v1
docker:
  imagePassthrough: true
  remoteBuild: true

A publish image override is also rejected because passthrough preserves the configured image reference unchanged.

Backward compatibility

imagePassthrough defaults to false. Existing behavior remains unchanged when the property is absent:

• source builds continue to build and publish normally;
• external source images can still be pulled, tagged, and copied to a configured destination registry;
• docker.remoteBuild continues to mean an ACR Tasks build with the existing local fallback behavior;
• existing remote --from-package short-circuits remain unchanged.

Implementation

• adds ImagePassthrough to DockerProjectOptions
• adds additive protobuf field image_passthrough = 11
• maps the field across core and extension SDK service configurations
• updates Docker required-tools, Build, Package, and Publish behavior
• keeps Container Apps and App Service publish metadata/validation consistent by routing passthrough through ContainerHelper.Publish
• supports the passthrough path in AKS Publish even when no package artifact is supplied directly
• adds v1.0 and alpha schema validation
• documents the new Docker option

Tests

cd cli/azd
go build ./...
go test ./pkg/project/...
go test ./... -short
go fix ./...

# Schema and diff validation
jq empty ../../schemas/v1.0/azure.yaml.json ../../schemas/alpha/azure.yaml.json
git diff --check

Coverage includes:

• no Docker/Podman requirement
• no Build operation for passthrough images
• Package emits an unchanged remote artifact without pull or tag
• Publish performs no login, pull, tag, or push even when a destination registry is configured
• Container Apps and App Service target publish paths
• service-image environment expansion
• missing-image validation
• remoteBuild conflict validation
• publish override conflict validation
• protobuf mapper round trips
• unchanged default external-image copy behavior

golangci-lint and cspell were unavailable locally; CI will run both.

[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.