Merge pull request #7465 from alexwolfmsft/compose-updates

Compose workflow and other miscellaneous updates

Author: Stacyrch140

articles/azure-developer-cli/azd-compose.md

@@ -13,17 +13,6 @@ ms.custom: devx-track-azdevcli, devx-track-bicep
 
 The Azure Developer CLI (`azd`) composability (compose) feature enables you to progressively compose the Azure resources required for your app without manually writing Bicep code. Compose also uses [Azure Verified Modules (AVM)](https://aka.ms/avm) when possible, providing recommended practices using building blocks for Azure.
 
-> [!NOTE]
-> The `azd` compose feature is currently in alpha and shouldn't be used in production apps. Changes to alpha features in subsequent releases can result in breaking changes. Visit the [azd feature versioning and release strategy](/azure/developer/azure-developer-cli/feature-versioning) and [feature stages](https://github.com/Azure/azure-dev/blob/main/cli/azd/docs/feature-stages.md) pages for more information. Use the **Feedback** button on the upper right to share feedback about the `compose` feature and this article.
-
-## Enable the compose feature
-
-The `azd` compose feature is currently in alpha, which means you need to enable it manually. Visit the [azd feature stages](https://aka.ms/azd-feature-stages) page for more information.
-
-```bash
-azd config set alpha.compose on
-```
-
 ## What is the compose feature?
 
 The `azd` compose feature offers a new way to get started with `azd`. Before the compose feature, developers had two primary options to configure the Azure resources to provision and deploy an application:
@@ -33,6 +22,13 @@ The `azd` compose feature offers a new way to get started with `azd`. Before the
 
 Any further customization required the user to manually modify the Bicep files—until the introduction of the compose feature.
 
+## Project compatability with compose
+
+The `azd` compose feature is designed for projects that don't already use infrastructure as code to manage Azure resources. As a result, compose does *not* support the following scenarios:
+
+- Projects that already have an `infra` folder for Azure resource creation (such as existing templates).
+- .NET Aspire projects, which use the Aspire app host file to manage resources.
+
 ### Streamline resource creation with compose
 
 The `azd` compose feature introduces a third option to add Azure resources to your apps. Developers use the `azd add` command to instruct `azd` to compose new Azure resources and update template configurations using minimal prompt workflows. This feature is useful for developers who want to avoid writing Bicep or using an existing template.

articles/azure-developer-cli/azd-init-workflow.md

@@ -17,13 +17,13 @@ The Azure Developer CLI (`azd`) provides a set of commands to streamline develop
 
 The `azd init` command supports several workflows to prepare your app to work with `azd`:
 
-- **Use code in the current directory**: Analyzes an existing app codebase to generate appropriate `azd` configuration files and resources.
+- **Scan current directory**: Analyzes an existing app codebase to generate appropriate `azd` configuration files and resources.
 - **Select a template**: Clones and initializes a template from an `azd` [template gallery](azd-template-galleries.md).
 - **Create a minimal project**: Initializes a basic `azure.yaml` file as a starting point for building your own `azd` template from scratch.
 
 Choose the approach that best fits your project. All of these flows are outlined in more detail in the [Create templates overview](make-azd-compatible.md) and related articles. The following sections provide a conceptual overview of each flow.
 
-### Use code in the current directory
+### Scan current directory
 
 Use this workflow when you have an existing app codebase and want to prepare it for deployment to Azure using `azd`.
 
@@ -34,13 +34,13 @@ Use this workflow when you have an existing app codebase and want to prepare it
     azd init
     ```
 
-3. Select **Use code in the current directory**. `azd` will:
+3. Select **Scan current directory**. `azd` will:
     - Scan your directory to determine the language or framework your app uses.
     - Select an appropriate hosting platform, such as Azure Container Apps.
     - Prompt you to add or remove discovered services if needed.
 
     ```output
-    ? How do you want to initialize your app? Use code in the current directory
+    ? How do you want to initialize your app? Scan current directory
 
       (✓) Done: Scanning app code in current directory
     
@@ -110,12 +110,9 @@ For advanced users who want to start with a minimal setup and customize everythi
 1. Run the `azd init` command:
 
    ```bash
-   azd init
+   azd init --minimal
    ```
 
-    > [!NOTE]
-    > You can also run `azd init` with the `--minimal` parameter to skip the workflow selection.
-
 2. When prompted, enter a name for your `azd` template and press Enter.
 
     ```output

articles/azure-developer-cli/compose-generate.md

@@ -13,12 +13,6 @@ ms.custom: devx-track-azdevcli, devx-track-bicep
 
 The Azure Developer CLI (`azd`) compose feature simplifies the process of building, deploying, and managing cloud applications. By using `azd compose`, you can define and manage the infrastructure and application code for your project in a unified way. This guide explains how to generate Bicep code from the `azd compose` feature, enabling you to customize your cloud infrastructure to meet your specific requirements.
 
-> [!NOTE]
-> The `azd infra synth` feature is currently in alpha status and must be enabled before use:
-> ```bash
-> azd config set alpha.infraSynth on
-> ```
-
 ## How `azd compose` manages infrastructure state
 
 The `azd compose` feature tracks your infrastructure state in-memory during the composition process. This approach allows you to iteratively define and refine your application and infrastructure without immediately generating files or modifying your project directory.
@@ -33,13 +27,29 @@ When you run the `azd infra synth` command, the in-memory state is converted int
 To explore or customize the Bicep code used internally by `azd` to provision resources created by `azd add`, run the following command:
 
 ```bash
-azd infra synth
+azd infra gen
 ```
 
+> [!NOTE]
+> The `azd infra synth` command from earlier versions of `azd` is now an alias of azd `infra generate`, and will continue to work. However, a warning message will be displayed and the command might be removed in a future `azd` release.
+
 This command generates the corresponding Bicep files in the `infra` folder of your app.
 
-> [!NOTE]
-> Running the `azd infra synth` command exits you from the `azd compose` feature and the simplified initialization process. Any changes you make to the generated Bicep files are not tracked by `azd compose`. For example, if you edit the Bicep code and then run `azd infra synth` again, `azd` overwrites your changes with the regenerated code.
+## Managing updates with Bicep generation
+
+When you run the `azd infra gen` command, you exit the `azd compose` workflow and the simplified init process. From this point on, any changes you make to the generated Bicep files are no longer tracked by `azd compose`. If you modify the Bicep files and later run `azd infra gen` again, your manual changes will be overwritten by the newly generated code.
+
+Here's how a typical workflow might look:
+
+1. You use `azd add` to add new Azure resources to your project. These resources are managed internally by `azd`.
+2. Once you've finished adding resources, you run `azd infra gen` to generate Bicep files for those resources in the project's `infra` folder. At this stage, the resources are no longer managed by the `azd compose` workflow.
+3. You can now manually update the Bicep files as you continue developing your app.
+4. If you add more resources or run `azd infra gen` again, the contents of the `infra` folder will be regenerated, and any manual changes will be lost.
+
+For this reason, the compose feature is best suited for the following scenarios:
+
+- Creating an initial set of Azure resources for your project, then managing further updates yourself by editing the Bicep files.
+- Managing your Azure resources entirely through the compose feature without running `azd infra gen`.
 
 ## Next steps
 

articles/azure-developer-cli/media/troubleshoot/error-resolving-azure-resource.png

@@ -282,6 +282,45 @@ DOCKER_BUILDKIT=1 DOCKER_BUILD_ARGS="--no-cache" azd up
 
 `azd pipeline config` is currently not supported in [DevContainers/VS Code Remote Containers](https://code.visualstudio.com/docs/devcontainers/containers).
 
+## Compose feature errors
+
+The `azd` compose feature is only available for specific project types. If you try to use compose commands like `azd add` or `azd infra gen` in an unsupported context, you may encounter the following errors.
+
+### Incompatible project
+
+If you see an `ERROR: incompatible project` message when running the `azd add` command, check the type of project you're working with. The `azd add` command is not supported for .NET Aspire projects or for `azd` templates that already have an `infra` folder defined. Attempting to use `azd add` with these project types will result in errors such as:
+
+* ERROR: incompatible project: found Aspire app host
+* ERROR: incompatible project: found infra directory and azure.yaml without resources
+
+    :::image type="content" source="media/troubleshoot/incompatible-project-aspire.png" alt-text="A screenshot showing the incompatible .NET Aspire project error.":::
+
+    :::image type="content" source="media/troubleshoot/incompatible-project-infra.png" alt-text="A screenshot showing the incompatible project infrastructure error.":::
+
+### Project does not contain infrastructure to generate
+
+The error `ERROR: this project does not contain any infrastructure to generate` occurs when:
+
+* You run `azd infra gen` without any compose resources defined in your project.
+* In .NET Aspire projects, this error can also appear if `azd` cannot detect an Aspire App Host in the current directory.
+
+To resolve this error, use `azd add` to add new resources before running `azd infra gen` or ensure your .NET Aspire project is structured correctly.
+
+:::image type="content" source="media/troubleshoot/no-infrastructure-generate.png" alt-text="A screenshot showing the infrastructure error.":::
+
+## Error resolving Azure resource
+
+The command `azd show <name>` might fail with the error: `ERROR: resolving '<name>': AZURE_RESOURCE_<NAME>_ID is not set as an output variable`. This could happen for a number of reasons:
+
+* The resource `<name>` does not exist in `azure.yaml` under the resources: node.
+* The resource `<name>` has not been provisioned yet.
+
+:::image type="content" source="media/troubleshoot/error-resolving-azure-resource.png" alt-text="A screenshot showing the azure resource error.":::
+
+### Solution
+
+Run `azd up` to provision the resources. You may need to run `azd infra gen` first to generate the updated Bicep including the resource `<name>`, then run `azd up`.
+
 ## Live metrics support for Python
 
 Live Metrics (`azd monitor --live`) is currently not supported for Python apps. For more information, see [Live Metrics: Monitor and diagnose with 1-second latency](/azure/azure-monitor/app/live-stream#get-started).