Merge pull request #290358 from MicrosoftDocs/release-ignite-deployment-environments

Ignite 2024 ship room - Force delete - Azure Deployment Environments - #335707

Author: MikeRayMSFT

articles/deployment-environments/how-to-manage-environments.md

@@ -7,12 +7,14 @@ ms.author: rosemalcolm
 ms.service: azure-deployment-environments
 ms.custom: devx-track-azurecli, build-2023
 ms.topic: how-to
-ms.date: 12/07/2023
+ms.date: 11/06/2024
+
+# customer intent: As a developer, I want to learn how to manage my environments in Azure Deployment Environments so that I can create, redeploy, and delete my environments as needed.
 ---
 
 # Manage environments in Azure Deployment Environments
 
-In this article, you learn how to manage environments in Azure Deployment Environments. As a developer, you can create and manage your environments from the developer portal or by using the Azure CLI.
+In this article, you learn how to manage environments in Azure Deployment Environments (ADE). As a developer, you can create and manage your environments from the developer portal or by using the Azure CLI.
 
 In Azure Deployment Environments, a platform engineer gives developers access to projects and the environment types that are associated with them. After a developer has access, they can create deployment environments based on the preconfigured environment types. The permissions are defined in the specific environment type.  
 
@@ -21,11 +23,13 @@ In Azure Deployment Environments, a platform engineer gives developers access to
 - Access to a project that has at least one environment type.
 - The [Deployment Environments User](how-to-configure-deployment-environments-user.md) role, the [DevCenter Project Admin](how-to-configure-project-admin.md) role, or a [built-in role](../role-based-access-control/built-in-roles.md) that has the required permissions to create an environment.
 
-## Manage an environment by using the developer portal
+## Create an environment by using the developer portal
 
 The developer portal provides a graphical interface for development teams to create new environments and manage existing environments in Azure Deployment Environments. You can create, redeploy, and delete your environments as needed in the developer portal.
 
-### Create an environment by using the developer portal
+When you create a deployment environment, ADE uses the environment definition to define the resources for your environment and creates a resource group to store them. 
+
+To create a deployment environment in the developer portal, follow these steps:
 
 1. Sign in to the [developer portal](https://devportal.microsoft.com).
 
@@ -46,7 +50,7 @@ The developer portal provides a graphical interface for development teams to cre
 
    If your environment is configured to accept parameters, you can enter them on a separate pane.
 
-   :::image type="content" source="media/how-to-manage-environments/parameter-pane.png" alt-text="Screenshot showing the parameter pane." lightbox="media/how-to-manage-environments/parameter-pane.png":::
+   :::image type="content" source="media/how-to-manage-environments/parameter-pane.png" alt-text="Screenshot of the developer portal showing the parameter pane." lightbox="media/how-to-manage-environments/parameter-pane.png":::
 
 1. Select **Create**. The environment tile is shown in the developer portal immediately, displaying the **Creating...** status while creation is in progress.
 
@@ -58,9 +62,9 @@ The developer portal provides a graphical interface for development teams to cre
 
    :::image type="content" source="media/how-to-manage-environments/environment-resources.png" alt-text="Screenshot showing environment resources in the Azure portal." lightbox="media/how-to-manage-environments/environment-resources.png":::
 
-### Redeploy an environment by using the developer portal
+## Redeploy an environment by using the developer portal
 
-When you need to update your environment, you can redeploy it. The redeployment process updates any existing resources with changed properties or creates any new resources based on the latest configuration of the environment definition.
+When you need to update your deployment environment, you can redeploy it. The redeployment process updates any existing resources with changed properties or creates any new resources based on the latest configuration of the environment definition.
 
 1. Sign in to the [developer portal](https://devportal.microsoft.com).
 
@@ -82,9 +86,9 @@ When you need to update your environment, you can redeploy it. The redeployment
 
    :::image type="content" source="media/how-to-manage-environments/redeployed-resources.png" alt-text="Screenshot showing redeployed resources in the Azure portal." lightbox="media/how-to-manage-environments/redeployed-resources.png":::
 
-### Delete an environment by using the developer portal
+## Delete an environment by using the developer portal
 
-You can delete your environment completely when you don't need it anymore.
+You can delete your deployment environment completely when you don't need it anymore. ADE uses the resource group and environment definition to identify and delete the resources created for the deployment environment.
 
 1. Sign in to the [developer portal](https://devportal.microsoft.com).
 
@@ -98,6 +102,28 @@ You can delete your environment completely when you don't need it anymore.
 
 1. The environment tile displays the status **Deleting...** while the deletion is in progress.
 
+## Force delete an environment
+
+An attempt to delete a deployment environment might fail due to issues like the environment definition being missing or inaccessible. It can also fail if the Azure Container Registry (ACR) that holds a custom runner isn't available, if Azure Deployment Environments (ADE) can't access the runner, or if updates cause the runner to function incorrectly.
+
+If the deletion fails, you can forcibly delete the environment. Force delete deletes the environment, its deployment resource group, and all resources in the deployment resource group. Any resources created outside the resource group are orphaned; force delete doesn't delete them.
+
+To forcibly delete an environment, follow these steps:
+1. Open the CLI.
+1. Run the following command to forcibly delete the environment:
+
+   ```bash
+   az devcenter environment delete --name <environment-name> --dev-center <dev-center-name> --project-name <project-name> --force
+   ```
+
+    Replace `<environment-name>` with the name of the environment you want to delete, `<dev-center-name>` with the name of your dev center, and `<project-name>` with the name of the project that the environment belongs to.
+
+For more information about the `az devcenter environment delete` command, see [az devcenter environment delete](/cli/azure/devcenter/dev/environment).
+
+> [!IMPORTANT]
+> The force delete feature is currently in PREVIEW.
+> For more information about the preview status, see the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). The document defines legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
+
 ## Manage an environment by using the Azure CLI
 
 The Azure CLI provides a command-line interface for speed and efficiency when you create multiple similar environments, or for platforms where resources like memory are limited. You can use the *devcenter* Azure CLI extension to create, list, deploy, or delete an environment in Azure Deployment Environments.