ADE - Updates for private repo support - Terraform

Author: RoseHJM

articles/deployment-environments/how-to-configure-extensibility-terraform-container-image.md

@@ -6,18 +6,18 @@ ms.service: azure-deployment-environments
 ms.custom: devx-track-azurecli, devx-track-terraform
 author: RoseHJM
 ms.author: rosemalcolm
-ms.date: 04/15/2024
+ms.date: 08/02/2024
 ms.topic: how-to
 #customer intent: As a developer, I want to learn how to build and utilize custom images within my environment definitions for deployment environments.
 ---
 
 # Configure a container image to execute deployments with Terraform
 
-In this article, you learn how to build custom Terraform container images to deploy your environment definitions in Azure Deployment Environments (ADE). You learn how to configure a custom image to provision infrastructure using the Terraform Infrastructure-as-Code (IaC) framework.
+In this article, you learn how to build custom Terraform container images to deploy your [environment definitions](configure-environment-definition.md) in Azure Deployment Environments (ADE). You learn how to configure a custom image to provision infrastructure using the Terraform Infrastructure-as-Code (IaC) framework.
 
 An environment definition comprises at least two files: a template file, like *main.tf*, and a manifest file named *environment.yaml*. You use a container to deploy environment definition that uses Terraform.
 
-The ADE extensibility model enables you to create custom container images to use with your environment definitions. By using the extensibility model, you can create your own custom container images, and store them in a container registry like DockerHub. You can then reference these images in your environment definitions to deploy your environments.
+The ADE extensibility model enables you to create custom container images to use with your environment definitions. By using the extensibility model, you can create your own custom container images, and store them in a container registry like Azure Container Registry (ACR) or DockerHub. You can then reference these images in your environment definitions to deploy your environments.
 
 ## Prerequisites
 
@@ -158,7 +158,9 @@ echo "{\"outputs\": $tfOutputs}" > $ADE_OUTPUTS
 ```
 ## Make the custom image accessible to ADE
 
-You must build your Docker image and push it to your container registry to make it available for use in ADE. You can build your image using the Docker CLI, or by using a script provided by ADE.
+You must build your Docker image and push it to your container registry to make it available for use in ADE. 
+
+You can build your image using the Docker CLI, or by using a script provided by ADE.
 
 Select the appropriate tab to learn more about each approach.
 
@@ -178,9 +180,16 @@ docker build . -t {YOUR_REGISTRY}.azurecr.io/customImage:1.0.0
 
 ## Push the Docker image to a registry
 
-In order to use custom images, you need to set up a publicly accessible image registry with anonymous image pull enabled. This way, Azure Deployment Environments can access your custom image to execute in our container.
+In order to use custom images, you need to store them in a registry like Azure Container Registry (ACR) or Docker Hub. 
+
+To use a custom image stored in a public registry, you need to enable anonymous image pull. This way, Azure Deployment Environments can access your custom image to execute in our container.
+
+> [!Caution]
+> Enabling anonymous (unauthenticated) pull access makes all registry content publicly available for read (pull) actions. 
+
+To use a custom image stored in ACR, you need to ensure that ADE has appropriate permissions to access your image. Anonymous pull access is disabled by default in ACR. 
 
-Azure Container Registry is an Azure offering that stores container images and similar artifacts.
+#### Use a public registry with anonymous pull
 
 To create a registry, which can be done through the Azure CLI, the Azure portal, PowerShell commands, and more, follow one of the [quickstarts](/azure/container-registry/container-registry-get-started-azure-cli).
 
@@ -199,6 +208,58 @@ When you're ready to push your image to your registry, run the following command
 docker push {YOUR_REGISTRY}.azurecr.io/{YOUR_IMAGE_LOCATION}:{YOUR_TAG}
 ```
 
+#### Use ACR with secured access
+
+By default, access to pull or push content from an Azure Container Registry is only available to authenticated users. You can further secure access to ACR by limiting access from certain networks and assigning specific roles.
+
+##### Limit network access
+
+To secure network access to your ACR, you can limit access to your own networks, or disable public network access entirely. If you limit network access, you must enable the firewall exception *Allow trusted Microsoft services to access this container registry*.
+
+To disable access from public networks:
+
+1. [Create an ACR instance](/azure/container-registry/container-registry-get-started-portal?tabs=azure-cli) or use an existing one.
+1. In the Azure portal, go to the ACR that you want to configure.
+1. On the left menu, under **Settings**, select **Networking**.
+1. On the Networking page, on the **Public access** tab, under **Public network access**, select **Disabled**.
+
+   :::image type="content" source="media/how-to-configure-extensibility-terraform-container-image/container-registry-network-settings.png" alt-text="Screenshot of the Azure portal, showing the ACR network settings, with Public access and Disabled highlighted."::: 
+
+1. Under **Firewall exception**, check that **Allow trusted Microsoft services to access this container registry** is selected, and then select **Save**.
+
+   :::image type="content" source="media/how-to-configure-extensibility-terraform-container-image/container-registry-network-disable-public.png" alt-text="Screenshot of the ACR network settings, with Allow trusted Microsoft services to access this container registry and Save highlighted.":::
+
+##### Assign the AcrPull role
+
+Creating environments by using container images uses the ADE infrastructure, including projects and environment types. Each project has one or more project environment types, which need read access to the container image that defines the environment to be deployed. To access the images within your ACR securely, assign the AcrPull role to each project environment type. 
+
+To assign the AcrPull role to the Project Environment Type:
+
+1. In the Azure portal, go to the ACR that you want to configure.
+1. On the left menu, select **Access Control (IAM)**.
+1. Select **Add** > **Add role assignment**.
+1. Assign the following role. For detailed steps, see [Assign Azure roles using the Azure portal](../role-based-access-control/role-assignments-portal.yml).
+
+    | Setting | Value |
+    | --- | --- |
+    | **Role** | Select **AcrPull**. |
+    | **Assign access to** | Select **User, group, or service principal**. |
+    | **Members** | Enter the name of the project environment type that needs to access the image in the container. |
+
+   The project environment type displays like the following example:
+
+   :::image type="content" source="media/how-to-configure-extensibility-terraform-container-image/container-registry-access-control-pet.png" alt-text="Screenshot of the Select members pane, showing a list of project environment types with part of the name highlighted.":::
+
+In this configuration, ADE uses the Managed Identity for the PET, whether system assigned or user assigned.
+
+> [!Tip]
+> This role assignment has to be made for every project environment type. It can be automated through the Azure CLI.
+When you're ready to push your image to your registry, run the following command:
+
+```docker
+docker push {YOUR_REGISTRY}.azurecr.io/{YOUR_IMAGE_LOCATION}:{YOUR_TAG}
+```
+
 ## [Build a container image with a script](#tab/build-a-container-image-with-a-script/)
 
 [!INCLUDE [custom-image-script](includes/custom-image-script.md)]