microsoft / microsoft/GitHub-Copilot-for-Azure

Improve azure-deploy / azure-prepare skills to handle ACA placeholder container image lifecycle

Open
#1,230 1 comment 0 reactions 0 assignees View on GitHub
enhancement untriaged
Dominant language
Python
Stars
250
Forks
204
Avg merge
1d 12h
Merged PRs (30d)
67

Description

## Summary

When using the `azure-prepare` or `azure-deploy` skills to deploy a containerized app to **Azure Container Apps** via `azd` + Bicep, users are often confused by the placeholder container image (`mcr.microsoft.com/azuredocs/containerapps-helloworld`) that appears after provisioning. The skills should proactively explain this behavior and guide users through it.

## Problem

`azd` uses a two-phase deployment lifecycle for Azure Container Apps:

1. **`azd provision`** — Creates infrastructure via Bicep. ARM requires a container image at resource-creation time, but the user's app image typically doesn't exist yet (especially with remote Docker builds). So azd scaffolds Bicep that uses a placeholder: `mcr.microsoft.com/azuredocs/containerapps-helloworld`.
2. **`azd deploy`** — Builds code, pushes to ACR, and updates the Container App with the user's real image.

This is **by design** ([source](https://github.com/Azure/azure-dev/blob/main/cli/azd/extensions/azure.ai.agents/internal/project/parser.go#L666-L684)), but creates several pain points:

- Users who run `azd provision` alone see the placeholder and think the deployment failed
- Re-provisioning can reset a previously deployed image back to the placeholder if the Bicep `exists` parameter isn't wired correctly via `fetch-container-image.bicep`
- Users who already have a pre-built image in ACR don't know they can skip the build by setting `docker.image` / `docker.registry` / `docker.tag` in `azure.yaml`, or by setting `SERVICE__IMAGE_NAME` via `azd env set`
- The per-service Bicep "controlled-revision deployment" (`infra/.bicep`) approach — the recommended production pattern — is not surfaced

## Proposed Improvements

### 1. Proactive guidance during Container Apps provisioning
When the skill generates Bicep for an ACA deployment, explain that:
- A placeholder image will be used during provisioning (this is expected)
- `azd deploy` (or `azd up`) must follow to deploy the real image
- The placeholder gets auto-deactivated after deploy

### 2. Wire the `exists` parameter correctly in generated Bicep
Ensure generated Bicep templates include:
- The `fetch-container-image.bicep` module
- The `param exists bool` parameter fed by `SERVICE__RESOURCE_EXISTS`
- Conditional logic so re-provisions preserve the running image

### 3. Support pre-built image scenarios
When a user says "I already have an image" or "deploy this image from ACR", the skill should:
- Set `docker.image`, `docker.registry`, and `docker.tag` in `azure.yaml`
- Or guide the user to `azd env set SERVICE__IMAGE_NAME myacr.azurecr.io/my-app:v1`

### 4. Surface the controlled-revision deployment pattern
For production deployments, recommend creating `infra/.bicep` (+ `.parameters.json`) so `azd deploy` uses atomic single-revision deployment instead of the two-phase placeholder dance.

### 5. Troubleshooting table in skill knowledge
Add awareness of common ACA + azd pitfalls:

| Problem | Cause | Fix |
|---|---|---|
| Placeholder image after provision | Normal — deploy hasn't run | Run `azd deploy` or `azd up` |
| Image resets on re-provision | `exists` param missing in Bicep | Wire `fetch-container-image.bicep` |
| "Container registry not found" | `AZURE_CONTAINER_REGISTRY_ENDPOINT` not set | `azd env set AZURE_CONTAINER_REGISTRY_ENDPOINT myacr.azurecr.io` |
| ACR auth errors | Missing `AcrPull` role | Assign `AcrPull` to the Container App's managed identity |
| Sidecars not updated | `azd deploy` only updates `containers[0].image` | Use per-service Bicep |

## References

- [azd source: placeholder comment](https://github.com/Azure/azure-dev/blob/main/cli/azd/extensions/azure.ai.agents/internal/project/parser.go#L666-L684)
- [fetch-container-image.bicep](https://github.com/Azure/azure-dev/blob/main/cli/azd/resources/scaffold/base/modules/fetch-container-image.bicep)
- [service_target_containerapp.go](https://github.com/Azure/azure-dev/blob/main/cli/azd/pkg/project/service_target_containerapp.go)
- [GitHub Issue azure-dev#3116](https://github.com/Azure/azure-dev/issues/3116)
- [azd schema docs](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/azd-schema)

Contributor guide

Open the contributing guide

Research direction

Start with the referenced azure-deploy and azure-prepare skills, then read fetch-container-image.bicep and service_target_containerapp.go to understand placeholder-image and exists handling. Compare the guidance with the linked azd parser source and schema documentation. Done means the skills explain the two-phase lifecycle, preserve images on re-provision, cover pre-built images and troubleshooting, and surface the controlled-revision pattern.

Written by the indexing model from the issue text.

Assessment

Tech stack
azure, docker
Domain
cloud, devops, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.